@rankwrangler/cli 0.9.0 → 0.11.0

package/README.md

@@ -7,18 +7,23 @@ npm install -g @rankwrangler/cli
 
 rw auth set ak_...
 rw product get B0DV53VS61
-rw product search "retro gardening shirt"
+rw product get B0DV53VS61 --shortName
+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/history/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.
 
 See the [CLI reference](../../docs/reference/cli.md) for options and release workflow.

package/dist/CHANGELOG.md

@@ -2,6 +2,64 @@
 
 All notable changes to this project will be documented in this file.
 
+## 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
+
+- Add optional `include` on `product.get` for `marketData`, `shortName`, and `cutoutThumbnail`.
+  The default remains `marketData`.
+- Add image-informed design short names. A Product get that includes `shortName` waits up to 20
+  seconds. `rw product get <asin> --shortName` requests that include together with `marketData`.
+  The response carries `listing.shortName`, or `null` when no name is ready.
+- Add on-demand transparent 128×128 cutout thumbnails through `cutoutThumbnail` on that same
+  `include` list. RankWrangler centers the subject and reuses the cutout until the listing image
+  changes.
+- Advertise the website URL and a 128px icon in hosted MCP server info.
+- Name the stale ingestion check on `GET /api/health` when the service is degraded, and include
+  the deployed commit as `revision` on both health responses.
+
+### Changed
+
+- Breaking: replace `isUnavailable` with `amazonListingStatus` (`active` or `deleted`) on Product
+  listings, search results, and basic `getMany` results. A deleted listing keeps its last-known
+  title and thumbnail. `active` means the Amazon detail page exists. The dashboard marks deleted
+  listings.
+- Return last-known `getMany` listings immediately and refresh stale listings in the background.
+  Short names and cutouts stay on single Product get.
+
+### Fixed
+
+- Show the server error when the dashboard Products read fails, and reserve the empty catalog
+  state for a successful read with no rows.
+- Load the API usage card across the UTC day boundary.
+- Fail an Amazon Catalog read that does not start within 2 minutes with a retryable capacity
+  error.
+- Require a second overdue Product before Keepa or SP-API freshness degrades `GET /api/health`,
+  and wait out a top search terms report that is still pending.
+
 ## v0.9.0 - 2026-08-09
 
 ### Added

package/dist/cli-keyword-command.js

@@ -1,8 +1,14 @@
 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);

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;
@@ -13,6 +35,7 @@ export interface CliOptionValues {
     bucket?: string;
     cursor?: string;
     refresh?: boolean;
+    shortName?: boolean;
     help?: boolean;
     version?: boolean;
 }

package/dist/cli-product-command.js

@@ -1,13 +1,17 @@
+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');
     }
     if (command.verb === 'get') {
         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);
@@ -19,26 +23,20 @@ export const runProductCommand = async (command, client, config, options, fail)
 const runProductGet = async (args, client, config, options, fail) => {
     const marketplaceId = requireMarketplaceId(options, config);
     const asins = requireAsins(args, fail);
+    if (asins.length > 1 && options.shortName) {
+        fail('INVALID_INPUT', '--shortName requires exactly one ASIN');
+    }
     if (asins.length === 1) {
         return await client.product.get.mutate({
             marketplaceId,
             asin: asins[0],
+            ...(options.shortName ? { include: ['marketData', 'shortName'] } : {}),
         });
     }
     return await client.product.getMany.mutate({
         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

@@ -17,6 +17,7 @@ const SUPPORTED_COMMANDS = new Set([
     'keyword:get',
     'keyword:search',
     'keyword:history',
+    'keyword:results',
     'auth:status',
     'auth:set',
     'auth:clear',
@@ -42,6 +43,29 @@ const { positionals, values } = parseArgs({
         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,
@@ -121,7 +145,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,12 @@ 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,7 +39,8 @@ 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)',
@@ -46,7 +48,22 @@ export const printUsage = (paths) => {
         '  --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 search offset',
+        '  --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',
@@ -65,7 +82,8 @@ 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',

package/package.json

@@ -1,7 +1,12 @@
 {
     "name": "@rankwrangler/cli",
-    "version": "0.9.0",
+    "version": "0.11.0",
     "description": "Official RankWrangler command line interface",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/merchbaseco/rankwrangler.git",
+        "directory": "packages/cli"
+    },
     "type": "module",
     "bin": {
         "rw": "dist/index.js",
@@ -24,8 +29,8 @@
         "provenance": true
     },
     "dependencies": {
-        "@merchbaseco/access": "0.3.0",
-        "@rankwrangler/http-client": "^0.9.0",
+        "@merchbaseco/access": "0.4.0",
+        "@rankwrangler/http-client": "^0.11.0",
         "keytar": "7.9.0"
     },
     "devDependencies": {

package/dist/history-response.d.ts

@@ -1,41 +0,0 @@
-export declare const HISTORY_METRIC_ALIASES: readonly ["bsr", "price"];
-export type HistoryMetricAlias = (typeof HISTORY_METRIC_ALIASES)[number];
-type HistoryPointTuple = [string, number | null] | [string, null, 1];
-export type AgentHistorySeries = {
-    bsr?: {
-        unit: 'rank';
-        category: {
-            id: number;
-            name: string | null;
-        } | null;
-        points: HistoryPointTuple[];
-    };
-    price?: {
-        unit: 'minorCurrency';
-        currencyCode: 'USD';
-        valueScale: 100;
-        points: HistoryPointTuple[];
-    };
-};
-export type AgentHistoryResponse = {
-    schemaVersion?: number;
-    status?: string;
-    syncTriggered: boolean;
-    latestImportAt: string | null;
-    series?: AgentHistorySeries;
-};
-export declare const buildCliHistoryResponse: ({ asin, marketplaceId, metrics, response, }: {
-    asin: string;
-    marketplaceId: string;
-    metrics: HistoryMetricAlias[];
-    response: AgentHistoryResponse;
-}) => {
-    schemaVersion: number;
-    asin: string;
-    marketplaceId: string;
-    status: string;
-    latestImportAt: string | null;
-    syncTriggered: boolean;
-    series: AgentHistorySeries;
-};
-export {};

package/dist/history-response.js

@@ -1,26 +0,0 @@
-export const HISTORY_METRIC_ALIASES = ['bsr', 'price'];
-export const buildCliHistoryResponse = ({ asin, marketplaceId, metrics, response, }) => {
-    const series = {
-        ...(metrics.includes('bsr') && response.series?.bsr ? { bsr: response.series.bsr } : {}),
-        ...(metrics.includes('price') && response.series?.price
-            ? { price: response.series.price }
-            : {}),
-    };
-    const hasAnyPoints = Object.values(series).some(metricSeries => metricSeries.points.length > 0);
-    const status = normalizeHistoryStatus(response.status);
-    return {
-        schemaVersion: response.schemaVersion ?? 1,
-        asin,
-        marketplaceId,
-        status: status ?? (response.syncTriggered ? 'collecting' : hasAnyPoints ? 'ready' : 'empty'),
-        latestImportAt: response.latestImportAt,
-        syncTriggered: response.syncTriggered,
-        series,
-    };
-};
-const normalizeHistoryStatus = (status) => {
-    if (status === 'ready' || status === 'collecting' || status === 'empty') {
-        return status;
-    }
-    return null;
-};