@rankwrangler/cli 0.6.0 → 0.9.0

package/README.md

@@ -1,75 +1,24 @@
 # @rankwrangler/cli
 
-Official CLI for RankWrangler.
-
-## Install
+Official agent-oriented CLI for RankWrangler.
 
 ```bash
 npm install -g @rankwrangler/cli
-```
-
-## Usage
-
-```bash
-rw --version
-rw changelog
-rw auth set rrk_...
-printf %s "$RR_LICENSE_KEY" | rw auth set --stdin
-rw config set storage-dir ~/.config/rankwrangler
-rw config get marketplace
-rw config unset marketplace
-rw products get B0DV53VS61
-rw products history B0DV53VS61 --metrics bsr,price --bucket week
-RR_LICENSE_KEY=rrk_... rw license status
-# `rankwrangler` is also supported as an alias
-```
-
-`rw auth set [licenseKey]` stores the license key in the platform secure store
-(`macOS Keychain` on macOS). `rw auth status` reports whether the CLI will use an env override,
-stored auth, or no auth. `rw auth set --stdin` reads the key from standard input for agents and
-scripts. `rw auth clear` removes the stored key.
-
-`rw config set storage-dir <path>` saves the active storage directory globally. After that, every
-CLI command reads and writes its non-secret config/data from that directory, while preserving
-existing config values when switching. `rw config get <key>`, `rw config unset <key>`, and
-`rw config reset` inspect or remove non-secret config without touching stored auth.
-`RR_LICENSE_KEY`, `RR_STORAGE_DIR`, `RR_API_URL`, and `RR_MARKETPLACE_ID` override saved CLI state
-when set for CI, automation, or agent runtimes.
-`rw products history` ensures product/history data before returning bucketed history (`auto`,
-`day`, `week`, or `month`), not raw point series. `rw --version` prints the installed CLI version.
-`rw changelog` prints the latest bundled release notes shipped with the package.
 
-## Development
-
-```bash
-bun run cli:build
-bun run cli:test:e2e
+rw auth set ak_...
+rw product get B0DV53VS61
+rw product search "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
 ```
 
-## Release (Maintainers)
-
-From repo root:
-
-```bash
-bun run release:bump patch
-bun install
-bun run release:collect-changelog-context
-# draft CHANGELOG.md entry from commit context
-bun run release:check
-bun run cli:build
-bun run release:check-cli-pack
-```
-
-Then publish:
-
-Publish `packages/http-client` first. `packages/cli` now fails fast on `npm publish` until the
-matching `@rankwrangler/http-client` version is already available on npm.
-
-```bash
-cd packages/cli
-node ../../scripts/release/with-npm-token.mjs npm whoami --userconfig ../../.npmrc
-node ../../scripts/release/with-npm-token.mjs npm publish --access public --userconfig ../../.npmrc
-```
+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 CLI does not expose Catalog, Operation, provider status, or polling commands.
 
-On macOS, the helper reads `NPM_TOKEN` from the environment first and otherwise falls back to the
-Keychain item `rankwrangler-npm-token` for account `$USER`.
+See the [CLI reference](../../docs/reference/cli.md) for options and release workflow.

package/dist/CHANGELOG.md

@@ -2,6 +2,62 @@
 
 All notable changes to this project will be documented in this file.
 
+## v0.9.0 - 2026-08-09
+
+### Added
+
+- Add short-lived typed Provider-attempt telemetry for Keepa and SP-API operations, including
+  outcome, latency, and error context for operator diagnostics.
+
+### Changed
+
+- Breaking: replace the `product.getMany` available/unavailable result union with one fixed shape
+  containing identity, nullable title, resolved thumbnail, and `isUnavailable`. Unavailable Amazon
+  listings retain their last-known title and thumbnail data.
+
+### Fixed
+
+- Advertise Claude-compatible MCP Product and keyword schemas so fresh chats can discover and call
+  `getMany` directly, with clear unavailable-listing semantics in the Product tool description.
+- Stop unavailable Products from triggering automatic Keepa synchronization when their dashboard
+  drawer opens.
+
+## v0.8.0 - 2026-08-09
+
+### Added
+
+- Add synchronous basic Product lookup for up to 200 marketplace/ASIN pairs through the public
+  API and hosted MCP, with smart single- or multi-ASIN routing in `rw product get`.
+- Add complete Product Search, source provenance, and nullable merch-listing classification to the
+  public Product intelligence surface.
+
+### Changed
+
+- Resolve public Product reads to policy-current, source-attributed results while batching cold
+  SP-API catalog work by marketplace and persisting every requested Product identity.
+
+### Fixed
+
+- Preserve unavailable listing data, stop repeatedly polling unavailable listings, and keep those
+  Products accessible from the dashboard drawer.
+- Expose the hosted MCP ingress correctly in production.
+
+## v0.7.0 - 2026-08-06
+
+### Added
+
+- Add typed Product and keyword `get`, `search`, and `history` contracts for agents and integrations.
+- Add Merchbase OAuth bearer authentication and centralized RankWrangler access metering across
+  public clients.
+
+### Changed
+
+- Breaking: replace the previous public client surface with the grouped `product.get`,
+  `product.search`, `product.history`, `keyword.get`, `keyword.search`, and `keyword.history`
+  procedures.
+- Return final source-attributed data and freshness through the public API while keeping Catalog,
+  Operation, polling, and provider orchestration internal.
+
 ## v0.6.0 - 2026-06-15
 
 ### Added
@@ -220,4 +276,5 @@ All notable changes to this project will be documented in this file.
 
 - Rename and standardize the typed npm client package to `@merchbase/rankwrangler-http-client`.
 - Set initial HTTP client package release to `0.1.0` in `packages/http-client/package.json`.
-- Document npm publish and versioning policy for the typed HTTP client in `docs/http-client-spec.md`.
+- Document npm publish and versioning policy for the typed HTTP client; the current owner is
+  `docs/reference/http-client.md`.

package/dist/cli-auth-error.d.ts

@@ -0,0 +1,5 @@
+export declare class CliAuthError extends Error {
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(code: string, message: string, details?: unknown);
+}

package/dist/cli-auth-error.js

@@ -0,0 +1,10 @@
+export class CliAuthError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = 'CliAuthError';
+        this.code = code;
+        this.details = details;
+    }
+}

package/dist/cli-auth.d.ts

@@ -1,6 +1,6 @@
-export declare const LICENSE_KEY_ENV_VAR = "RR_LICENSE_KEY";
-export declare const AUTH_SERVICE_NAME = "RankWrangler CLI";
-export declare const AUTH_ACCOUNT_NAME = "license-key";
+export declare const API_KEY_ENV_VAR = "MERCHBASE_API_KEY";
+export declare const AUTH_SERVICE_NAME = "co.merchbase.cli";
+export declare const AUTH_ACCOUNT_NAME = "api-key";
 type CliFail = (code: string, message: string, details?: unknown) => never;
 type AuthCommand = {
     verb: string;
@@ -9,11 +9,6 @@ type AuthCommand = {
 type AuthCommandOptions = {
     stdin?: boolean;
 };
-export declare class CliAuthError extends Error {
-    readonly code: string;
-    readonly details?: unknown;
-    constructor(code: string, message: string, details?: unknown);
-}
 export declare const resolveApiKey: () => Promise<string | undefined>;
 export declare const runAuthCommand: (command: AuthCommand, fail: CliFail, options?: AuthCommandOptions) => Promise<{
     source: string;
@@ -23,7 +18,7 @@ export declare const runAuthCommand: (command: AuthCommand, fail: CliFail, optio
         serviceName: string;
         accountName: string;
         available: boolean;
-        hasStoredLicenseKey: boolean;
+        hasStoredApiKey: boolean;
         error?: undefined;
     };
 } | {
@@ -34,7 +29,7 @@ export declare const runAuthCommand: (command: AuthCommand, fail: CliFail, optio
         serviceName: string;
         accountName: string;
         available: boolean;
-        hasStoredLicenseKey: null;
+        hasStoredApiKey: null;
         error: string;
     };
 } | {
@@ -46,7 +41,7 @@ export declare const runAuthCommand: (command: AuthCommand, fail: CliFail, optio
         serviceName: string;
         accountName: string;
         available: boolean;
-        hasStoredLicenseKey: boolean;
+        hasStoredApiKey: boolean;
         error?: undefined;
     };
 } | {
@@ -58,7 +53,7 @@ export declare const runAuthCommand: (command: AuthCommand, fail: CliFail, optio
         serviceName: string;
         accountName: string;
         available: boolean;
-        hasStoredLicenseKey: null;
+        hasStoredApiKey: null;
         error: string;
     };
 } | {
@@ -70,7 +65,7 @@ export declare const runAuthCommand: (command: AuthCommand, fail: CliFail, optio
         serviceName: string;
         accountName: string;
         available: boolean;
-        hasStoredLicenseKey: boolean;
+        hasStoredApiKey: boolean;
         error?: undefined;
     };
 } | {
@@ -82,7 +77,7 @@ export declare const runAuthCommand: (command: AuthCommand, fail: CliFail, optio
         serviceName: string;
         accountName: string;
         available: boolean;
-        hasStoredLicenseKey: null;
+        hasStoredApiKey: null;
         error: string;
     };
 }>;
@@ -94,7 +89,7 @@ export declare const buildAuthStatus: () => Promise<{
         serviceName: string;
         accountName: string;
         available: boolean;
-        hasStoredLicenseKey: boolean;
+        hasStoredApiKey: boolean;
         error?: undefined;
     };
 } | {
@@ -105,7 +100,7 @@ export declare const buildAuthStatus: () => Promise<{
         serviceName: string;
         accountName: string;
         available: boolean;
-        hasStoredLicenseKey: null;
+        hasStoredApiKey: null;
         error: string;
     };
 }>;

package/dist/cli-auth.js

@@ -2,24 +2,16 @@ import { spawnSync } from 'node:child_process';
 import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import readline from 'node:readline';
-export const LICENSE_KEY_ENV_VAR = 'RR_LICENSE_KEY';
-export const AUTH_SERVICE_NAME = 'RankWrangler CLI';
-export const AUTH_ACCOUNT_NAME = 'license-key';
+import { MERCHBASE_API_KEY_ENV, MERCHBASE_API_KEY_KEYCHAIN_ACCOUNT, MERCHBASE_API_KEY_KEYCHAIN_SERVICE, } from '@merchbaseco/access';
+import { CliAuthError } from './cli-auth-error.js';
+export const API_KEY_ENV_VAR = MERCHBASE_API_KEY_ENV;
+export const AUTH_SERVICE_NAME = MERCHBASE_API_KEY_KEYCHAIN_SERVICE;
+export const AUTH_ACCOUNT_NAME = MERCHBASE_API_KEY_KEYCHAIN_ACCOUNT;
 const INTERNAL_SECRET_STORE_DIR_ENV_VAR = 'RW_INTERNAL_CLI_SECRET_STORE_DIR';
-export class CliAuthError extends Error {
-    code;
-    details;
-    constructor(code, message, details) {
-        super(message);
-        this.name = 'CliAuthError';
-        this.code = code;
-        this.details = details;
-    }
-}
 export const resolveApiKey = async () => {
-    const envLicenseKey = resolveEnvLicenseKey();
-    if (envLicenseKey) {
-        return envLicenseKey;
+    const envApiKey = resolveEnvApiKey();
+    if (envApiKey) {
+        return envApiKey;
     }
     const secureStore = await createSecureStore();
     return (await secureStore.get()) ?? undefined;
@@ -48,32 +40,32 @@ export const runAuthCommand = async (command, fail, options = {}) => {
     fail('UNKNOWN_COMMAND', 'Unknown auth command', { verb: command.verb });
 };
 export const buildAuthStatus = async () => {
-    const envLicenseKey = resolveEnvLicenseKey();
+    const envApiKey = resolveEnvApiKey();
     try {
         const secureStore = await createSecureStore();
-        const storedLicenseKey = await secureStore.get();
+        const storedApiKey = await secureStore.get();
         return {
-            source: envLicenseKey ? 'env' : storedLicenseKey ? 'secure-store' : 'none',
-            envOverride: Boolean(envLicenseKey),
+            source: envApiKey ? 'env' : storedApiKey ? 'secure-store' : 'none',
+            envOverride: Boolean(envApiKey),
             secureStore: {
                 backend: secureStore.backend,
                 serviceName: secureStore.serviceName,
                 accountName: secureStore.accountName,
                 available: true,
-                hasStoredLicenseKey: Boolean(storedLicenseKey),
+                hasStoredApiKey: Boolean(storedApiKey),
             },
         };
     }
     catch (error) {
         return {
-            source: envLicenseKey ? 'env' : 'none',
-            envOverride: Boolean(envLicenseKey),
+            source: envApiKey ? 'env' : 'none',
+            envOverride: Boolean(envApiKey),
             secureStore: {
                 backend: getSecureStoreBackendLabel(),
                 serviceName: AUTH_SERVICE_NAME,
                 accountName: AUTH_ACCOUNT_NAME,
                 available: false,
-                hasStoredLicenseKey: null,
+                hasStoredApiKey: null,
                 error: error instanceof Error ? error.message : 'Unknown secure-store error',
             },
         };
@@ -89,20 +81,20 @@ const resolveAuthSetValue = async (args, fail, options) => {
         if (stdinValue) {
             return stdinValue;
         }
-        fail('INVALID_INPUT', 'auth set --stdin received an empty license key');
+        fail('INVALID_INPUT', 'auth set --stdin received an empty API key');
     }
-    const envLicenseKey = resolveEnvLicenseKey();
-    if (envLicenseKey) {
-        return envLicenseKey;
+    const envApiKey = resolveEnvApiKey();
+    if (envApiKey) {
+        return envApiKey;
     }
     if (process.stdin.isTTY && process.stderr.isTTY) {
-        const promptValue = await readSecretFromPrompt('RankWrangler license key: ');
+        const promptValue = await readSecretFromPrompt('Merchbase API key: ');
         if (promptValue) {
             return promptValue;
         }
-        fail('INVALID_INPUT', 'auth set received an empty license key');
+        fail('INVALID_INPUT', 'auth set received an empty API key');
     }
-    fail('INVALID_INPUT', `auth set requires <licenseKey>, --stdin, or ${LICENSE_KEY_ENV_VAR}`);
+    fail('INVALID_INPUT', `auth set requires <apiKey>, --stdin, or ${API_KEY_ENV_VAR}`);
 };
 const readSecretFromStdin = async () => {
     const chunks = [];
@@ -139,8 +131,8 @@ const setTerminalEcho = (enabled) => {
         stdio: ['inherit', 'ignore', 'ignore'],
     });
 };
-const resolveEnvLicenseKey = () => {
-    const value = process.env[LICENSE_KEY_ENV_VAR]?.trim();
+const resolveEnvApiKey = () => {
+    const value = process.env[API_KEY_ENV_VAR]?.trim();
     return value ? value : undefined;
 };
 const createSecureStore = async () => {
@@ -178,7 +170,7 @@ const getSecureStoreBackendLabel = () => {
     }
 };
 const createFileSecretStore = (secretStoreDir) => {
-    const secretPath = path.join(secretStoreDir, 'license-key.json');
+    const secretPath = path.join(secretStoreDir, 'api-key.json');
     return {
         backend: 'test-file-store',
         serviceName: AUTH_SERVICE_NAME,
@@ -187,7 +179,7 @@ const createFileSecretStore = (secretStoreDir) => {
             try {
                 const raw = await readFile(secretPath, 'utf8');
                 const parsed = JSON.parse(raw);
-                return typeof parsed.licenseKey === 'string' ? parsed.licenseKey : null;
+                return typeof parsed.apiKey === 'string' ? parsed.apiKey : null;
             }
             catch (error) {
                 if (error &&
@@ -201,7 +193,7 @@ const createFileSecretStore = (secretStoreDir) => {
         },
         set: async (value) => {
             await mkdir(secretStoreDir, { recursive: true });
-            await writeFile(secretPath, `${JSON.stringify({ licenseKey: value }, null, 2)}\n`, 'utf8');
+            await writeFile(secretPath, `${JSON.stringify({ apiKey: value }, null, 2)}\n`, 'utf8');
         },
         clear: async () => {
             try {

package/dist/cli-config-command.d.ts

@@ -17,7 +17,7 @@ export declare const runConfigCommand: (command: ConfigCommand, config: CliConfi
             serviceName: string;
             accountName: string;
             available: boolean;
-            hasStoredLicenseKey: boolean;
+            hasStoredApiKey: boolean;
             error?: undefined;
         };
     } | {
@@ -28,7 +28,7 @@ export declare const runConfigCommand: (command: ConfigCommand, config: CliConfi
             serviceName: string;
             accountName: string;
             available: boolean;
-            hasStoredLicenseKey: null;
+            hasStoredApiKey: null;
             error: string;
         };
     };
@@ -49,7 +49,7 @@ export declare const runConfigCommand: (command: ConfigCommand, config: CliConfi
             serviceName: string;
             accountName: string;
             available: boolean;
-            hasStoredLicenseKey: boolean;
+            hasStoredApiKey: boolean;
             error?: undefined;
         };
     } | {
@@ -60,7 +60,7 @@ export declare const runConfigCommand: (command: ConfigCommand, config: CliConfi
             serviceName: string;
             accountName: string;
             available: boolean;
-            hasStoredLicenseKey: null;
+            hasStoredApiKey: null;
             error: string;
         };
     };
@@ -80,7 +80,7 @@ export declare const runConfigCommand: (command: ConfigCommand, config: CliConfi
             serviceName: string;
             accountName: string;
             available: boolean;
-            hasStoredLicenseKey: boolean;
+            hasStoredApiKey: boolean;
             error?: undefined;
         };
     } | {
@@ -91,7 +91,7 @@ export declare const runConfigCommand: (command: ConfigCommand, config: CliConfi
             serviceName: string;
             accountName: string;
             available: boolean;
-            hasStoredLicenseKey: null;
+            hasStoredApiKey: null;
             error: string;
         };
     };

package/dist/cli-keyword-command.d.ts

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

package/dist/cli-keyword-command.js

@@ -0,0 +1,69 @@
+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 === 'get') {
+        return await runKeywordGet(command.args, client, 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}`,
+    });
+};
+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),
+        limit: parseIntegerOption({
+            value: options.limit,
+            optionName: 'limit',
+            min: 1,
+            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) => {
+    const keyword = args.join(' ').trim();
+    if (!keyword) {
+        fail('INVALID_INPUT', `${commandName} requires text`);
+    }
+    return keyword;
+};

package/dist/cli-options.d.ts

@@ -1,22 +1,24 @@
 import type { CliConfig } from './cli-config';
-import { type HistoryBucket, type HistoryMetricAlias } from './history-response';
+import { type HistoryBucket, type HistoryMetricAlias } from './history-options';
 type CliFail = (code: string, message: string, details?: unknown) => never;
-export type CliOptionValues = {
+export interface CliOptionValues {
     baseUrl?: string;
     marketplace?: string;
-    asin?: string[];
     metrics?: string;
     startAt?: string;
     endAt?: string;
     days?: string;
+    rangeDays?: string;
     limit?: string;
     bucket?: string;
+    cursor?: string;
+    refresh?: boolean;
     help?: boolean;
     version?: boolean;
-};
+}
 export declare const requireMarketplaceId: (values: CliOptionValues, config: CliConfig) => string;
-export declare const requireAsins: (commandArgs: string[], values: CliOptionValues, fail: CliFail) => string[];
-export declare const requireSingleAsin: (commandArgs: string[], values: CliOptionValues, fail: CliFail) => string;
+export declare const requireSingleAsin: (commandArgs: string[], fail: CliFail, commandName?: string) => string;
+export declare const requireAsins: (commandArgs: string[], fail: CliFail, commandName?: string) => string[];
 export declare const resolveHistoryMetrics: (values: CliOptionValues, fail: CliFail) => HistoryMetricAlias[];
 export declare const resolveHistoryBucket: (values: CliOptionValues, fail: CliFail) => HistoryBucket;
 export declare const resolveHistoryWindow: (values: CliOptionValues, fail: CliFail) => {

package/dist/cli-options.js

@@ -1,31 +1,34 @@
-import { HISTORY_BUCKETS, HISTORY_METRIC_ALIASES, } from './history-response.js';
+import { HISTORY_BUCKETS, HISTORY_METRIC_ALIASES, } from './history-options.js';
 const ASIN_REGEX = /^[A-Z0-9]{10}$/i;
 const TRAILING_SLASHES_REGEX = /\/+$/;
 const API_SUFFIX_REGEX = /\/api$/i;
 const DEFAULT_MARKETPLACE_ID = 'ATVPDKIKX0DER';
 export const requireMarketplaceId = (values, config) => {
-    return values.marketplace ?? config.marketplaceId ?? process.env.RR_MARKETPLACE_ID ?? DEFAULT_MARKETPLACE_ID;
+    return (values.marketplace ??
+        config.marketplaceId ??
+        process.env.RR_MARKETPLACE_ID ??
+        DEFAULT_MARKETPLACE_ID);
 };
-export const requireAsins = (commandArgs, values, fail) => {
-    const candidates = [...commandArgs, ...(values.asin ?? []), ...resolveEnvAsins()]
-        .map(value => value.trim())
-        .filter(Boolean);
-    if (candidates.length === 0) {
-        fail('INVALID_INPUT', 'at least one asin is required');
+export const requireSingleAsin = (commandArgs, fail, commandName = 'product history') => {
+    if (commandArgs.length !== 1) {
+        fail('INVALID_INPUT', `${commandName} requires exactly one ASIN`);
     }
-    return Array.from(new Set(candidates.map(value => normalizeAsin(value, fail))));
+    return normalizeAsin(commandArgs[0] ?? '', fail);
 };
-export const requireSingleAsin = (commandArgs, values, fail) => {
-    const asins = requireAsins(commandArgs, values, fail);
-    if (asins.length !== 1) {
-        fail('INVALID_INPUT', 'products history requires exactly one asin');
+export const requireAsins = (commandArgs, fail, commandName = 'product get') => {
+    if (commandArgs.length < 1 || commandArgs.length > 200) {
+        fail('INVALID_INPUT', `${commandName} requires between 1 and 200 ASINs`);
+    }
+    const asins = commandArgs.map(value => normalizeAsin(value, fail));
+    if (new Set(asins).size !== asins.length) {
+        fail('INVALID_INPUT', `${commandName} requires unique ASINs`);
     }
-    return asins[0];
+    return asins;
 };
 export const resolveHistoryMetrics = (values, fail) => {
-    const requested = (values.metrics ?? process.env.RR_HISTORY_METRICS ?? 'bsr,price')
+    const requested = (values.metrics ?? process.env.RR_HISTORY_METRICS ?? 'salesRank,price')
         .split(',')
-        .map(value => value.trim().toLowerCase())
+        .map(value => normalizeHistoryMetric(value.trim()))
         .filter(Boolean);
     if (requested.length === 0) {
         fail('INVALID_INPUT', 'metrics cannot be empty');
@@ -48,7 +51,9 @@ export const resolveHistoryBucket = (values, fail) => {
     return requested;
 };
 export const resolveHistoryWindow = (values, fail) => {
-    const startAt = values.startAt ? normalizeDateOption('startAt', values.startAt, fail) : undefined;
+    const startAt = values.startAt
+        ? normalizeDateOption('startAt', values.startAt, fail)
+        : undefined;
     const endAt = values.endAt ? normalizeDateOption('endAt', values.endAt, fail) : undefined;
     if (values.days && (startAt || endAt)) {
         fail('INVALID_INPUT', 'use --days or --startAt/--endAt, not both');
@@ -69,7 +74,10 @@ export const resolveBaseUrl = (values, config, defaultBaseUrl, fail) => {
     return normalizeBaseUrl(values.baseUrl ?? config.baseUrl ?? process.env.RR_API_URL ?? defaultBaseUrl, fail);
 };
 export const normalizeBaseUrl = (value, fail) => {
-    const normalized = value.trim().replace(TRAILING_SLASHES_REGEX, '').replace(API_SUFFIX_REGEX, '');
+    const normalized = value
+        .trim()
+        .replace(TRAILING_SLASHES_REGEX, '')
+        .replace(API_SUFFIX_REGEX, '');
     if (!normalized) {
         fail('INVALID_INPUT', 'base url cannot be empty');
     }
@@ -99,9 +107,12 @@ const normalizeAsin = (value, fail) => {
     }
     return normalized;
 };
-const resolveEnvAsins = () => {
-    return [
-        ...(process.env.RR_ASINS ? process.env.RR_ASINS.split(',') : []),
-        ...(process.env.RR_ASIN ? [process.env.RR_ASIN] : []),
-    ];
+const normalizeHistoryMetric = (value) => {
+    if (value.toLowerCase() === 'salesrank') {
+        return 'salesRank';
+    }
+    if (value.toLowerCase() === 'price') {
+        return 'price';
+    }
+    return value;
 };

package/dist/cli-output.js

@@ -1,4 +1,4 @@
-import { CliAuthError } from './cli-auth.js';
+import { CliAuthError } from './cli-auth-error.js';
 import { CliStorageError } from './cli-config.js';
 const OUTPUT_PRETTY = true;
 export const printSuccess = (data) => {

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

@@ -0,0 +1,10 @@
+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;
+type CliClient = ReturnType<typeof createRankWranglerClient>;
+export declare const runProductCommand: (command: {
+    verb: string;
+    args: string[];
+}, client: CliClient, config: CliConfig, options: CliOptionValues, fail: CliFail) => Promise<unknown>;
+export {};

package/dist/cli-product-command.js

@@ -0,0 +1,62 @@
+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 (command.verb === 'get') {
+        return await runProductGet(command.args, client, config, options, fail);
+    }
+    if (command.verb === 'search') {
+        return await runProductSearch(command.args, client, options, fail);
+    }
+    if (command.verb === 'history') {
+        return await runProductHistory(command.args, client, config, options, fail);
+    }
+    fail('UNKNOWN_COMMAND', 'Unknown Product command', {
+        command: `product ${command.verb}`,
+    });
+};
+const runProductGet = async (args, client, config, options, fail) => {
+    const marketplaceId = requireMarketplaceId(options, config);
+    const asins = requireAsins(args, fail);
+    if (asins.length === 1) {
+        return await client.product.get.mutate({
+            marketplaceId,
+            asin: asins[0],
+        });
+    }
+    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);
+    return await client.product.history.mutate({
+        marketplaceId: requireMarketplaceId(options, config),
+        asin,
+        ...historyOptions,
+    });
+};
+const resolveHistoryOptions = (options, fail) => ({
+    metrics: resolveHistoryMetrics(options, fail),
+    bucket: resolveHistoryBucket(options, fail),
+    limit: parseIntegerOption({
+        value: options.limit,
+        optionName: 'limit',
+        min: 1,
+        max: 10_000,
+        defaultValue: 5000,
+    }, fail),
+    ...resolveHistoryWindow(options, fail),
+});

package/dist/history-options.d.ts

@@ -0,0 +1,4 @@
+export declare const HISTORY_METRIC_ALIASES: readonly ["salesRank", "price"];
+export declare const HISTORY_BUCKETS: readonly ["auto", "day", "week", "month"];
+export type HistoryMetricAlias = (typeof HISTORY_METRIC_ALIASES)[number];
+export type HistoryBucket = (typeof HISTORY_BUCKETS)[number];

package/dist/history-options.js

@@ -0,0 +1,2 @@
+export const HISTORY_METRIC_ALIASES = ['salesRank', 'price'];
+export const HISTORY_BUCKETS = ['auto', 'day', 'week', 'month'];

package/dist/history-response.d.ts

@@ -1,17 +1,6 @@
 export declare const HISTORY_METRIC_ALIASES: readonly ["bsr", "price"];
-export declare const HISTORY_BUCKETS: readonly ["auto", "day", "week", "month"];
 export type HistoryMetricAlias = (typeof HISTORY_METRIC_ALIASES)[number];
-export type HistoryBucket = (typeof HISTORY_BUCKETS)[number];
-type HistoryBucketTuple = [string, number | null];
-type HistoryBucketSummary = {
-    first: number | null;
-    latest: number | null;
-    min: number | null;
-    max: number | null;
-    count: number;
-    firstBucketAt: string | null;
-    latestBucketAt: string | null;
-};
+type HistoryPointTuple = [string, number | null] | [string, null, 1];
 export type AgentHistorySeries = {
     bsr?: {
         unit: 'rank';
@@ -19,15 +8,13 @@ export type AgentHistorySeries = {
             id: number;
             name: string | null;
         } | null;
-        buckets: HistoryBucketTuple[];
-        summary: HistoryBucketSummary;
+        points: HistoryPointTuple[];
     };
     price?: {
         unit: 'minorCurrency';
         currencyCode: 'USD';
         valueScale: 100;
-        buckets: HistoryBucketTuple[];
-        summary: HistoryBucketSummary;
+        points: HistoryPointTuple[];
     };
 };
 export type AgentHistoryResponse = {
@@ -35,11 +22,6 @@ export type AgentHistoryResponse = {
     status?: string;
     syncTriggered: boolean;
     latestImportAt: string | null;
-    range?: {
-        startAt: string;
-        endAt: string;
-        bucket: Exclude<HistoryBucket, 'auto'>;
-    };
     series?: AgentHistorySeries;
 };
 export declare const buildCliHistoryResponse: ({ asin, marketplaceId, metrics, response, }: {
@@ -48,17 +30,12 @@ export declare const buildCliHistoryResponse: ({ asin, marketplaceId, metrics, r
     metrics: HistoryMetricAlias[];
     response: AgentHistoryResponse;
 }) => {
-    series: AgentHistorySeries;
-    range?: {
-        startAt: string;
-        endAt: string;
-        bucket: Exclude<HistoryBucket, "auto">;
-    } | undefined;
     schemaVersion: number;
     asin: string;
     marketplaceId: string;
     status: string;
     latestImportAt: string | null;
     syncTriggered: boolean;
+    series: AgentHistorySeries;
 };
 export {};

package/dist/history-response.js

@@ -1,5 +1,4 @@
 export const HISTORY_METRIC_ALIASES = ['bsr', 'price'];
-export const HISTORY_BUCKETS = ['auto', 'day', 'week', 'month'];
 export const buildCliHistoryResponse = ({ asin, marketplaceId, metrics, response, }) => {
     const series = {
         ...(metrics.includes('bsr') && response.series?.bsr ? { bsr: response.series.bsr } : {}),
@@ -7,16 +6,15 @@ export const buildCliHistoryResponse = ({ asin, marketplaceId, metrics, response
             ? { price: response.series.price }
             : {}),
     };
-    const hasAnyBuckets = Object.values(series).some(metricSeries => metricSeries.buckets.length > 0);
+    const hasAnyPoints = Object.values(series).some(metricSeries => metricSeries.points.length > 0);
     const status = normalizeHistoryStatus(response.status);
     return {
-        schemaVersion: response.schemaVersion ?? 2,
+        schemaVersion: response.schemaVersion ?? 1,
         asin,
         marketplaceId,
-        status: status ?? (response.syncTriggered ? 'collecting' : hasAnyBuckets ? 'ready' : 'empty'),
+        status: status ?? (response.syncTriggered ? 'collecting' : hasAnyPoints ? 'ready' : 'empty'),
         latestImportAt: response.latestImportAt,
         syncTriggered: response.syncTriggered,
-        ...(response.range ? { range: response.range } : {}),
         series,
     };
 };

package/dist/index.js

@@ -2,18 +2,21 @@
 import { parseArgs } from 'node:util';
 import { createRankWranglerClient, DEFAULT_API_BASE_URL } from '@rankwrangler/http-client';
 import { resolveApiKey, runAuthCommand } from './cli-auth.js';
-import { printBundledChangelog, printCliVersion } from './cli-metadata.js';
-import { runConfigCommand } from './cli-config-command.js';
 import { loadCliContext, loadCliPathsOrDefault } from './cli-config.js';
-import { parseIntegerOption, requireAsins, requireMarketplaceId, requireSingleAsin, resolveBaseUrl, resolveHistoryBucket, resolveHistoryMetrics, resolveHistoryWindow, } from './cli-options.js';
+import { runConfigCommand } from './cli-config-command.js';
+import { runKeywordCommand } from './cli-keyword-command.js';
+import { printBundledChangelog, printCliVersion } from './cli-metadata.js';
+import { resolveBaseUrl } from './cli-options.js';
 import { fail, printSuccess, resolveError } from './cli-output.js';
-import { buildCliHistoryResponse } from './history-response.js';
+import { runProductCommand } from './cli-product-command.js';
 import { printUsage } from './usage.js';
 const SUPPORTED_COMMANDS = new Set([
-    'products:get',
-    'products:history',
-    'license:status',
-    'license:validate',
+    'product:get',
+    'product:search',
+    'product:history',
+    'keyword:get',
+    'keyword:search',
+    'keyword:history',
     'auth:status',
     'auth:set',
     'auth:clear',
@@ -30,13 +33,15 @@ const { positionals, values } = parseArgs({
         version: { type: 'boolean' },
         baseUrl: { type: 'string' },
         marketplace: { type: 'string', short: 'm' },
-        asin: { type: 'string', multiple: true },
         metrics: { type: 'string' },
         startAt: { type: 'string' },
         endAt: { type: 'string' },
         days: { type: 'string' },
+        rangeDays: { type: 'string' },
         limit: { type: 'string' },
         bucket: { type: 'string' },
+        cursor: { type: 'string' },
+        refresh: { type: 'boolean' },
         stdin: { type: 'boolean' },
     },
     allowPositionals: true,
@@ -52,11 +57,9 @@ const main = async () => {
         process.exit(values.help ? 0 : 1);
     }
     const metaCommand = resolveMetaCommand(positionals);
-    if (metaCommand) {
-        if (metaCommand.name === 'changelog') {
-            printBundledChangelog();
-            return;
-        }
+    if (metaCommand?.name === 'changelog') {
+        printBundledChangelog();
+        return;
     }
     const command = resolveCommandOrFail(positionals);
     if (!isSupportedCommand(command)) {
@@ -70,72 +73,32 @@ const main = async () => {
         return;
     }
     if (command.resource === 'auth') {
-        printSuccess(await runAuthCommand(command, fail, { stdin: Boolean(values.stdin) }));
+        printSuccess(await runAuthCommand(command, fail, {
+            stdin: Boolean(values.stdin),
+        }));
         return;
     }
     const apiKey = await resolveApiKey();
     if (!apiKey) {
-        fail('MISSING_CONFIG', 'license key is required. run `rw auth set`, `rw auth set --stdin`, or set RR_LICENSE_KEY');
+        fail('MISSING_CONFIG', 'Merchbase API key is required. run `rw auth set`, `rw auth set --stdin`, or set MERCHBASE_API_KEY');
     }
     const client = createRankWranglerClient({
         baseUrl: resolveBaseUrl(optionValues, config, DEFAULT_API_BASE_URL, fail),
         apiKey,
     });
-    printSuccess(await runApiCommand(command, client, config));
+    printSuccess(await runApiCommand(command, client, config, optionValues));
 };
-const runApiCommand = async (command, client, config) => {
-    if (command.resource === 'products' && command.verb === 'get') {
-        const optionValues = values;
-        const marketplaceId = requireMarketplaceId(optionValues, config);
-        const asins = requireAsins(command.args, optionValues, fail);
-        if (asins.length === 1) {
-            return client.getProductInfo.mutate({ marketplaceId, asin: asins[0] });
-        }
-        return client.getProductInfoBatch.mutate({ marketplaceId, asins });
-    }
-    if (command.resource === 'products' && command.verb === 'history') {
-        return runProductHistoryCommand(command, client, config);
+const runApiCommand = async (command, client, config, options) => {
+    if (command.resource === 'product') {
+        return await runProductCommand(command, client, config, options, fail);
     }
-    if (command.resource === 'license' && command.verb === 'status') {
-        return client.license.status.mutate();
-    }
-    if (command.resource === 'license' && command.verb === 'validate') {
-        return client.license.validate.mutate();
+    if (command.resource === 'keyword') {
+        return await runKeywordCommand(command, client, options, fail);
     }
     fail('UNKNOWN_COMMAND', 'Unknown command', {
         command: `${command.resource} ${command.verb}`,
     });
 };
-const runProductHistoryCommand = async (command, client, config) => {
-    const optionValues = values;
-    const asin = requireSingleAsin(command.args, optionValues, fail);
-    const marketplaceId = requireMarketplaceId(optionValues, config);
-    const metrics = resolveHistoryMetrics(optionValues, fail);
-    const bucket = resolveHistoryBucket(optionValues, fail);
-    const historyWindow = resolveHistoryWindow(optionValues, fail);
-    const limit = parseIntegerOption({
-        value: optionValues.limit,
-        optionName: 'limit',
-        min: 1,
-        max: 10000,
-        defaultValue: 5000,
-    }, fail);
-    const response = await client.getProductHistory.mutate({
-        marketplaceId,
-        asin,
-        metrics,
-        format: 'agent',
-        bucket,
-        limit,
-        ...historyWindow,
-    });
-    return buildCliHistoryResponse({
-        asin,
-        marketplaceId,
-        metrics,
-        response: response,
-    });
-};
 const resolveMetaCommand = (inputPositionals) => {
     if (inputPositionals.length === 1 && inputPositionals[0] === 'changelog') {
         return { name: 'changelog' };
@@ -144,7 +107,7 @@ const resolveMetaCommand = (inputPositionals) => {
 };
 const resolveCommand = (inputPositionals) => {
     const [first, second, ...rest] = inputPositionals;
-    if (!first || !second) {
+    if (!(first && second)) {
         return null;
     }
     return {
@@ -161,9 +124,7 @@ const resolveCommandOrFail = (inputPositionals) => {
     fail('UNKNOWN_COMMAND', 'Unknown command', { command: inputPositionals.join(' ') });
     throw new Error('unreachable');
 };
-const isSupportedCommand = (command) => {
-    return SUPPORTED_COMMANDS.has(`${command.resource}:${command.verb}`);
-};
+const isSupportedCommand = (command) => SUPPORTED_COMMANDS.has(`${command.resource}:${command.verb}`);
 await main().catch(error => {
     const resolved = resolveError(error);
     fail(resolved.code, resolved.message, resolved.details);

package/dist/usage.js

@@ -1,4 +1,4 @@
-import { LICENSE_KEY_ENV_VAR } from './cli-auth.js';
+import { API_KEY_ENV_VAR } from './cli-auth.js';
 const DEFAULT_MARKETPLACE_ID = 'ATVPDKIKX0DER';
 export const printUsage = (paths) => {
     const usage = [
@@ -15,12 +15,14 @@ export const printUsage = (paths) => {
         '',
         'COMMANDS',
         '  changelog',
-        '  products get <ASIN...>',
-        '  products history <ASIN>',
-        '  license status',
-        '  license validate',
+        '  product get <ASIN...>',
+        '  product search <keyword>',
+        '  product history <ASIN>',
+        '  keyword get <keyword>',
+        '  keyword search <text>',
+        '  keyword history <keyword>',
         '  auth status',
-        '  auth set [licenseKey]',
+        '  auth set [apiKey]',
         '  auth set --stdin',
         '  auth clear',
         '  config show',
@@ -36,13 +38,15 @@ export const printUsage = (paths) => {
         '  --version                Print the CLI version',
         '  --baseUrl <origin>       Override API origin',
         `  -m, --marketplace <id>   Override marketplace (default: ${DEFAULT_MARKETPLACE_ID})`,
-        '  --asin <ASIN>            Add ASIN (repeatable)',
-        '  --metrics <list>         History metrics: bsr,price (default: bsr,price)',
-        '  --bucket <unit>          History buckets: auto,day,week,month (default: auto)',
-        '  --days <N>               History lookback window (30-3650, default: 365)',
-        '  --startAt <ISO>          History range start (ISO date/time)',
-        '  --endAt <ISO>            History range end (ISO date/time)',
-        '  --limit <N>              Internal point cap (1-10000, default: 5000)',
+        '  --refresh                Product search refresh (separate Search contract)',
+        '  --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)',
         '  --stdin                  Read auth secret from standard input',
         '',
         'FILES',
@@ -50,27 +54,26 @@ export const printUsage = (paths) => {
         `  ${paths.globalConfigPath}           Global CLI settings`,
         '',
         'ENVIRONMENT',
-        `  ${LICENSE_KEY_ENV_VAR}           License key override for CI/automation`,
+        `  ${API_KEY_ENV_VAR}           Merchbase API key override for CI/automation`,
         '  RR_API_URL               API origin fallback',
         '  RR_MARKETPLACE_ID        Marketplace fallback',
         '  RR_STORAGE_DIR           Storage directory override',
-        '  RR_ASIN                  Single ASIN fallback',
-        '  RR_ASINS                 Comma-separated ASIN fallback',
-        '  RR_HISTORY_METRICS       Comma-separated history metrics fallback',
+        '  RR_HISTORY_METRICS       Comma-separated product history metrics fallback',
         '',
         'EXAMPLES',
-        '  rw auth set rrk_...',
-        '  printf %s "$RR_LICENSE_KEY" | rw auth set --stdin',
-        `  ${LICENSE_KEY_ENV_VAR}=rrk_... rw products get B0DV53VS61`,
+        '  rw auth set ak_...',
+        '  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 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',
-        '  rw config get marketplace',
-        '  rw config set storage-dir ~/.config/rankwrangler',
-        '  rw config unset marketplace',
-        '  rw products history B0DV53VS61 --metrics bsr,price --bucket week',
-        '  rw products history B0DV53VS61 --startAt 2025-01-01 --endAt 2025-12-31 --bucket month',
-        '  rankwrangler license status',
+        '  rankwrangler auth status',
     ];
     console.log(usage.join('\n'));
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rankwrangler/cli",
-    "version": "0.6.0",
+    "version": "0.9.0",
     "description": "Official RankWrangler command line interface",
     "type": "module",
     "bin": {
@@ -16,7 +16,7 @@
     "scripts": {
         "build": "tsc -p tsconfig.json && node scripts/fix-dist-imports.mjs && node scripts/sync-changelog.mjs",
         "prepack": "node scripts/sync-changelog.mjs",
-        "test:e2e": "bun test test/index.e2e.test.ts",
+        "test:e2e": "bun test test/*.e2e.test.ts",
         "prepublishOnly": "node ../../scripts/release/ensure-cli-http-client-published.mjs"
     },
     "publishConfig": {
@@ -24,7 +24,8 @@
         "provenance": true
     },
     "dependencies": {
-        "@rankwrangler/http-client": "^0.6.0",
+        "@merchbaseco/access": "0.3.0",
+        "@rankwrangler/http-client": "^0.9.0",
         "keytar": "7.9.0"
     },
     "devDependencies": {