@rankwrangler/cli 0.5.0 → 0.8.0

package/README.md

@@ -1,68 +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_...
-rw config set storage-dir ~/.config/rankwrangler
-rw products get B0DV53VS61
-rw products history B0DV53VS61 --metrics bsr,price
-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 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. `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 --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
-```
+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.
 
-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
-set -a
-source ../../.env
-set +a
-npm whoami --userconfig ../../.npmrc
-npm publish --access public --userconfig ../../.npmrc
-```
+See the [CLI reference](../../docs/reference/cli.md) for options and release workflow.

package/dist/CHANGELOG.md

@@ -2,6 +2,60 @@
 
 All notable changes to this project will be documented in this file.
 
+## 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
+
+- Add `rw auth set --stdin` and hidden local auth entry so agents can pipe license keys and humans
+  can avoid shell history.
+- Add `rw config get`, `rw config unset`, and `rw config reset` for explicit non-secret config
+  inspection and cleanup.
+
+### Changed
+
+- Show auth source/status in `rw config show` without printing secrets.
+- Update CLI help, README, CLI spec, and e2e coverage for the clearer auth/config surface.
+
+### Removed
+
+- Remove `rw config clear` in favor of `rw config unset <key>` and `rw config reset`.
+
 ## v0.5.0 - 2026-03-18
 
 ### Added
@@ -202,4 +256,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,18 +1,16 @@
-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;
     args: string[];
 };
-export declare class CliAuthError extends Error {
-    readonly code: string;
-    readonly details?: unknown;
-    constructor(code: string, message: string, details?: unknown);
-}
+type AuthCommandOptions = {
+    stdin?: boolean;
+};
 export declare const resolveApiKey: () => Promise<string | undefined>;
-export declare const runAuthCommand: (command: AuthCommand, fail: CliFail) => Promise<{
+export declare const runAuthCommand: (command: AuthCommand, fail: CliFail, options?: AuthCommandOptions) => Promise<{
     source: string;
     envOverride: boolean;
     secureStore: {
@@ -20,7 +18,7 @@ export declare const runAuthCommand: (command: AuthCommand, fail: CliFail) => Pr
         serviceName: string;
         accountName: string;
         available: boolean;
-        hasStoredLicenseKey: boolean;
+        hasStoredApiKey: boolean;
         error?: undefined;
     };
 } | {
@@ -31,7 +29,7 @@ export declare const runAuthCommand: (command: AuthCommand, fail: CliFail) => Pr
         serviceName: string;
         accountName: string;
         available: boolean;
-        hasStoredLicenseKey: null;
+        hasStoredApiKey: null;
         error: string;
     };
 } | {
@@ -43,7 +41,7 @@ export declare const runAuthCommand: (command: AuthCommand, fail: CliFail) => Pr
         serviceName: string;
         accountName: string;
         available: boolean;
-        hasStoredLicenseKey: boolean;
+        hasStoredApiKey: boolean;
         error?: undefined;
     };
 } | {
@@ -55,7 +53,7 @@ export declare const runAuthCommand: (command: AuthCommand, fail: CliFail) => Pr
         serviceName: string;
         accountName: string;
         available: boolean;
-        hasStoredLicenseKey: null;
+        hasStoredApiKey: null;
         error: string;
     };
 } | {
@@ -67,7 +65,7 @@ export declare const runAuthCommand: (command: AuthCommand, fail: CliFail) => Pr
         serviceName: string;
         accountName: string;
         available: boolean;
-        hasStoredLicenseKey: boolean;
+        hasStoredApiKey: boolean;
         error?: undefined;
     };
 } | {
@@ -79,7 +77,30 @@ export declare const runAuthCommand: (command: AuthCommand, fail: CliFail) => Pr
         serviceName: string;
         accountName: string;
         available: boolean;
-        hasStoredLicenseKey: null;
+        hasStoredApiKey: null;
+        error: string;
+    };
+}>;
+export declare const buildAuthStatus: () => Promise<{
+    source: string;
+    envOverride: boolean;
+    secureStore: {
+        backend: string;
+        serviceName: string;
+        accountName: string;
+        available: boolean;
+        hasStoredApiKey: boolean;
+        error?: undefined;
+    };
+} | {
+    source: string;
+    envOverride: boolean;
+    secureStore: {
+        backend: string;
+        serviceName: string;
+        accountName: string;
+        available: boolean;
+        hasStoredApiKey: null;
         error: string;
     };
 }>;

package/dist/cli-auth.js

@@ -1,33 +1,27 @@
+import { spawnSync } from 'node:child_process';
 import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-export const LICENSE_KEY_ENV_VAR = 'RR_LICENSE_KEY';
-export const AUTH_SERVICE_NAME = 'RankWrangler CLI';
-export const AUTH_ACCOUNT_NAME = 'license-key';
+import readline from 'node:readline';
+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;
 };
-export const runAuthCommand = async (command, fail) => {
+export const runAuthCommand = async (command, fail, options = {}) => {
     if (command.verb === 'status') {
         return buildAuthStatus();
     }
     if (command.verb === 'set') {
-        const value = resolveAuthSetValue(command.args, fail);
+        const value = await resolveAuthSetValue(command.args, fail, options);
         const secureStore = await createSecureStore();
         await secureStore.set(value);
         return {
@@ -45,51 +39,100 @@ export const runAuthCommand = async (command, fail) => {
     }
     fail('UNKNOWN_COMMAND', 'Unknown auth command', { verb: command.verb });
 };
-const buildAuthStatus = async () => {
-    const envLicenseKey = resolveEnvLicenseKey();
+export const buildAuthStatus = async () => {
+    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',
             },
         };
     }
 };
-const resolveAuthSetValue = (args, fail) => {
+const resolveAuthSetValue = async (args, fail, options) => {
     const positionalValue = args.join(' ').trim();
     if (positionalValue) {
         return positionalValue;
     }
-    const envLicenseKey = resolveEnvLicenseKey();
-    if (envLicenseKey) {
-        return envLicenseKey;
+    if (options.stdin) {
+        const stdinValue = await readSecretFromStdin();
+        if (stdinValue) {
+            return stdinValue;
+        }
+        fail('INVALID_INPUT', 'auth set --stdin received an empty API key');
     }
-    fail('INVALID_INPUT', `auth set requires <licenseKey> or ${LICENSE_KEY_ENV_VAR}`);
+    const envApiKey = resolveEnvApiKey();
+    if (envApiKey) {
+        return envApiKey;
+    }
+    if (process.stdin.isTTY && process.stderr.isTTY) {
+        const promptValue = await readSecretFromPrompt('Merchbase API key: ');
+        if (promptValue) {
+            return promptValue;
+        }
+        fail('INVALID_INPUT', 'auth set received an empty API key');
+    }
+    fail('INVALID_INPUT', `auth set requires <apiKey>, --stdin, or ${API_KEY_ENV_VAR}`);
+};
+const readSecretFromStdin = async () => {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString('utf8').trim();
+};
+const readSecretFromPrompt = async (prompt) => {
+    process.stderr.write(prompt);
+    setTerminalEcho(false);
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stderr,
+        terminal: true,
+    });
+    try {
+        const value = await new Promise(resolve => {
+            rl.question('', resolve);
+        });
+        process.stderr.write('\n');
+        return value.trim();
+    }
+    finally {
+        rl.close();
+        setTerminalEcho(true);
+    }
+};
+const setTerminalEcho = (enabled) => {
+    if (process.platform === 'win32' || !process.stdin.isTTY) {
+        return;
+    }
+    spawnSync('stty', [enabled ? 'echo' : '-echo'], {
+        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 () => {
@@ -127,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,
@@ -136,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 &&
@@ -150,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

@@ -9,11 +9,93 @@ export declare const runConfigCommand: (command: ConfigCommand, config: CliConfi
     path: string;
     globalPath: string;
     config: CliConfig;
+    auth: {
+        source: string;
+        envOverride: boolean;
+        secureStore: {
+            backend: string;
+            serviceName: string;
+            accountName: string;
+            available: boolean;
+            hasStoredApiKey: boolean;
+            error?: undefined;
+        };
+    } | {
+        source: string;
+        envOverride: boolean;
+        secureStore: {
+            backend: string;
+            serviceName: string;
+            accountName: string;
+            available: boolean;
+            hasStoredApiKey: null;
+            error: string;
+        };
+    };
 } | {
-    cleared: boolean;
+    key: "base-url" | "marketplace" | "storage-dir";
+    value: string | null;
+} | {
+    unset: "base-url" | "marketplace" | "storage-dir";
+    storageDir: string;
+    path: string;
+    globalPath: string;
+    config: CliConfig;
+    auth: {
+        source: string;
+        envOverride: boolean;
+        secureStore: {
+            backend: string;
+            serviceName: string;
+            accountName: string;
+            available: boolean;
+            hasStoredApiKey: boolean;
+            error?: undefined;
+        };
+    } | {
+        source: string;
+        envOverride: boolean;
+        secureStore: {
+            backend: string;
+            serviceName: string;
+            accountName: string;
+            available: boolean;
+            hasStoredApiKey: null;
+            error: string;
+        };
+    };
+    key?: undefined;
+    value?: undefined;
+} | {
+    reset: boolean;
     storageDir: string;
     path: string;
     globalPath: string;
     config: CliConfig;
+    auth: {
+        source: string;
+        envOverride: boolean;
+        secureStore: {
+            backend: string;
+            serviceName: string;
+            accountName: string;
+            available: boolean;
+            hasStoredApiKey: boolean;
+            error?: undefined;
+        };
+    } | {
+        source: string;
+        envOverride: boolean;
+        secureStore: {
+            backend: string;
+            serviceName: string;
+            accountName: string;
+            available: boolean;
+            hasStoredApiKey: null;
+            error: string;
+        };
+    };
+    key?: undefined;
+    value?: undefined;
 }>;
 export {};

package/dist/cli-config-command.js

@@ -1,14 +1,31 @@
-import { clearConfig, saveConfig, switchStorageDir } from './cli-config.js';
+import { buildAuthStatus } from './cli-auth.js';
+import { resetConfig, saveConfig, switchStorageDir, unsetStorageDir, } from './cli-config.js';
 import { normalizeBaseUrl } from './cli-options.js';
+const CONFIG_KEYS = ['base-url', 'marketplace', 'storage-dir'];
 export const runConfigCommand = async (command, config, paths, fail) => {
     if (command.verb === 'show') {
         return buildConfigResponse(paths, config);
     }
-    if (command.verb === 'clear') {
-        await clearConfig(paths);
+    if (command.verb === 'get') {
+        const key = requireConfigKey(command.args[0], 'config get', fail);
         return {
-            ...buildConfigResponse(paths, {}),
-            cleared: true,
+            key,
+            value: getConfigValue(key, paths, config),
+        };
+    }
+    if (command.verb === 'unset') {
+        const key = requireConfigKey(command.args[0], 'config unset', fail);
+        const nextState = await unsetConfigValue(key, paths, config);
+        return {
+            ...(await buildConfigResponse(nextState.paths, nextState.config)),
+            unset: key,
+        };
+    }
+    if (command.verb === 'reset') {
+        const nextState = await resetConfig(paths);
+        return {
+            ...(await buildConfigResponse(nextState.paths, nextState.config)),
+            reset: true,
         };
     }
     if (command.verb !== 'set') {
@@ -38,19 +55,64 @@ export const runConfigCommand = async (command, config, paths, fail) => {
         nextConfig.marketplaceId = value;
     }
     else {
-        fail('INVALID_INPUT', 'unsupported config key', {
-            key,
-            supportedKeys: ['base-url', 'marketplace', 'storage-dir'],
-        });
+        failUnsupportedConfigKey(key, fail);
     }
     await saveConfig(paths, nextConfig);
     return buildConfigResponse(paths, nextConfig);
 };
-const buildConfigResponse = (paths, config) => {
+const buildConfigResponse = async (paths, config) => {
     return {
         storageDir: paths.storageDir,
         path: paths.configPath,
         globalPath: paths.globalConfigPath,
         config,
+        auth: await buildAuthStatus(),
+    };
+};
+const requireConfigKey = (key, commandName, fail) => {
+    if (!key) {
+        fail('INVALID_INPUT', `${commandName} requires <key>`, {
+            supportedKeys: CONFIG_KEYS,
+        });
+    }
+    if (isConfigKey(key)) {
+        return key;
+    }
+    return failUnsupportedConfigKey(key, fail);
+};
+const isConfigKey = (key) => {
+    return CONFIG_KEYS.includes(key);
+};
+const getConfigValue = (key, paths, config) => {
+    switch (key) {
+        case 'base-url':
+            return config.baseUrl ?? null;
+        case 'marketplace':
+            return config.marketplaceId ?? null;
+        case 'storage-dir':
+            return paths.storageDir;
+    }
+};
+const unsetConfigValue = async (key, paths, config) => {
+    if (key === 'storage-dir') {
+        return unsetStorageDir(paths);
+    }
+    const nextConfig = { ...config };
+    if (key === 'base-url') {
+        nextConfig.baseUrl = undefined;
+    }
+    else {
+        nextConfig.marketplaceId = undefined;
+    }
+    await saveConfig(paths, nextConfig);
+    return {
+        paths,
+        config: nextConfig,
     };
 };
+const failUnsupportedConfigKey = (key, fail) => {
+    fail('INVALID_INPUT', 'unsupported config key', {
+        key,
+        supportedKeys: CONFIG_KEYS,
+    });
+};

package/dist/cli-config.d.ts

@@ -19,8 +19,15 @@ export declare const loadCliContext: () => Promise<{
     config: CliConfig;
 }>;
 export declare const loadCliPathsOrDefault: () => Promise<CliPaths>;
-export declare const clearConfig: (paths: CliPaths) => Promise<void>;
+export declare const resetConfig: (paths: CliPaths) => Promise<{
+    paths: CliPaths;
+    config: {};
+}>;
 export declare const saveConfig: (paths: CliPaths, config: CliConfig) => Promise<void>;
+export declare const unsetStorageDir: (paths: CliPaths) => Promise<{
+    paths: CliPaths;
+    config: CliConfig;
+}>;
 export declare const switchStorageDir: ({ currentConfig, currentPaths, requestedStorageDir, }: {
     currentConfig: CliConfig;
     currentPaths: CliPaths;