@rankwrangler/cli 0.2.2 → 0.4.0

package/README.md

@@ -11,19 +11,41 @@ npm install -g @rankwrangler/cli
 ## Usage
 
 ```bash
-rw config set api-key rrk_...
+export RR_LICENSE_KEY=rrk_...
+rw config set storage-dir ~/.config/rankwrangler
 rw products get B0DV53VS61
+rw products history B0DV53VS61 --metrics bsr,price
 # `rankwrangler` is also supported as an alias
 ```
 
+`RR_LICENSE_KEY` is the API-key source. `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_STORAGE_DIR`, `RR_API_URL`, and `RR_MARKETPLACE_ID` override saved CLI config when set.
+
 ## Development
 
 ```bash
 bun run cli:build
+bun run cli:test:e2e
 ```
 
 ## 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:
+
 ```bash
 cd packages/cli
 set -a
@@ -32,7 +54,3 @@ set +a
 npm whoami --userconfig ../../.npmrc
 npm publish --access public --userconfig ../../.npmrc
 ```
-
-If npm rejects the version as already published, bump `version` in
-`packages/cli/package.json` to match the next `vX.Y.Z` release in `CHANGELOG.md`,
-run `bun install` from repo root, and publish again.

package/dist/cli-config.d.ts

@@ -0,0 +1,31 @@
+export type CliConfig = {
+    baseUrl?: string;
+    marketplaceId?: string;
+};
+export type CliPaths = {
+    defaultStorageDir: string;
+    storageDir: string;
+    configPath: string;
+    globalConfigPath: string;
+};
+export declare class CliStorageError extends Error {
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(code: string, message: string, details?: unknown);
+}
+export declare const getDefaultCliPaths: () => CliPaths;
+export declare const loadCliContext: () => Promise<{
+    paths: CliPaths;
+    config: CliConfig;
+}>;
+export declare const loadCliPathsOrDefault: () => Promise<CliPaths>;
+export declare const clearConfig: (paths: CliPaths) => Promise<void>;
+export declare const saveConfig: (paths: CliPaths, config: CliConfig) => Promise<void>;
+export declare const switchStorageDir: ({ currentConfig, currentPaths, requestedStorageDir, }: {
+    currentConfig: CliConfig;
+    currentPaths: CliPaths;
+    requestedStorageDir: string;
+}) => Promise<{
+    paths: CliPaths;
+    config: CliConfig;
+}>;

package/dist/cli-config.js

@@ -0,0 +1,136 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+const DEFAULT_STORAGE_DIR = path.join(homedir(), '.rankwrangler');
+const CONFIG_FILENAME = 'config.json';
+const GLOBAL_CONFIG_FILENAME = 'global.json';
+const STORAGE_DIR_ENV_VAR = 'RR_STORAGE_DIR';
+export class CliStorageError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = 'CliStorageError';
+        this.code = code;
+        this.details = details;
+    }
+}
+export const getDefaultCliPaths = () => {
+    return buildCliPaths(DEFAULT_STORAGE_DIR);
+};
+export const loadCliContext = async () => {
+    const paths = await resolveCliPaths();
+    const config = await loadConfig(paths.configPath);
+    return {
+        paths,
+        config,
+    };
+};
+export const loadCliPathsOrDefault = async () => {
+    try {
+        return await resolveCliPaths();
+    }
+    catch {
+        return getDefaultCliPaths();
+    }
+};
+export const clearConfig = async (paths) => {
+    await rm(paths.configPath, { force: true });
+};
+export const saveConfig = async (paths, config) => {
+    await mkdir(paths.storageDir, { recursive: true });
+    await writeFile(paths.configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+};
+export const switchStorageDir = async ({ currentConfig, currentPaths, requestedStorageDir, }) => {
+    const storageDir = normalizeStorageDir(requestedStorageDir);
+    const nextPaths = buildCliPaths(storageDir);
+    const targetConfig = await loadConfig(nextPaths.configPath);
+    const nextConfig = mergeConfigs(currentConfig, targetConfig);
+    await saveConfig(nextPaths, nextConfig);
+    await saveGlobalConfig(currentPaths.globalConfigPath, {
+        storageDir: storageDir === currentPaths.defaultStorageDir ? undefined : storageDir,
+    });
+    return {
+        paths: nextPaths,
+        config: nextConfig,
+    };
+};
+const resolveCliPaths = async () => {
+    const defaults = getDefaultCliPaths();
+    const globalConfig = await loadGlobalConfig(defaults.globalConfigPath);
+    const storageDir = normalizeStorageDir(process.env[STORAGE_DIR_ENV_VAR] ?? globalConfig.storageDir ?? defaults.storageDir);
+    return buildCliPaths(storageDir);
+};
+const buildCliPaths = (storageDir) => {
+    return {
+        defaultStorageDir: DEFAULT_STORAGE_DIR,
+        storageDir,
+        configPath: path.join(storageDir, CONFIG_FILENAME),
+        globalConfigPath: path.join(DEFAULT_STORAGE_DIR, GLOBAL_CONFIG_FILENAME),
+    };
+};
+const loadConfig = async (configPath) => {
+    const parsed = await readJsonFile(configPath, 'failed to read config');
+    if (!parsed) {
+        return {};
+    }
+    return {
+        baseUrl: typeof parsed.baseUrl === 'string' ? parsed.baseUrl : undefined,
+        marketplaceId: typeof parsed.marketplaceId === 'string' ? parsed.marketplaceId : undefined,
+    };
+};
+const loadGlobalConfig = async (globalConfigPath) => {
+    const parsed = await readJsonFile(globalConfigPath, 'failed to read global config');
+    if (!parsed) {
+        return {};
+    }
+    return {
+        storageDir: typeof parsed.storageDir === 'string' ? parsed.storageDir : undefined,
+    };
+};
+const saveGlobalConfig = async (globalConfigPath, config) => {
+    if (!config.storageDir) {
+        await rm(globalConfigPath, { force: true });
+        return;
+    }
+    await mkdir(path.dirname(globalConfigPath), { recursive: true });
+    await writeFile(globalConfigPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+};
+const readJsonFile = async (filePath, errorMessage) => {
+    try {
+        const raw = await readFile(filePath, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        if (error &&
+            typeof error === 'object' &&
+            'code' in error &&
+            error.code === 'ENOENT') {
+            return null;
+        }
+        throw new CliStorageError('INVALID_CONFIG', errorMessage, { path: filePath });
+    }
+};
+const normalizeStorageDir = (value) => {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new CliStorageError('INVALID_INPUT', 'storage dir cannot be empty');
+    }
+    const expanded = expandHomeDirectory(trimmed);
+    return path.resolve(expanded);
+};
+const expandHomeDirectory = (value) => {
+    if (value === '~') {
+        return homedir();
+    }
+    if (value.startsWith('~/')) {
+        return path.join(homedir(), value.slice(2));
+    }
+    return value;
+};
+const mergeConfigs = (currentConfig, targetConfig) => {
+    return {
+        baseUrl: targetConfig.baseUrl ?? currentConfig.baseUrl,
+        marketplaceId: targetConfig.marketplaceId ?? currentConfig.marketplaceId,
+    };
+};

package/dist/cli-options.d.ts

@@ -0,0 +1,34 @@
+import type { CliConfig } from './cli-config';
+import { type HistoryMetricAlias } from './history-response';
+type CliFail = (code: string, message: string, details?: unknown) => never;
+export type CliOptionValues = {
+    baseUrl?: string;
+    marketplace?: string;
+    asin?: string[];
+    metrics?: string;
+    startAt?: string;
+    endAt?: string;
+    days?: string;
+    limit?: string;
+    help?: 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 resolveHistoryMetrics: (values: CliOptionValues, fail: CliFail) => HistoryMetricAlias[];
+export declare const resolveHistoryWindow: (values: CliOptionValues, fail: CliFail) => {
+    days: number;
+    endAt?: string | undefined;
+    startAt?: string | undefined;
+};
+export declare const resolveApiKey: () => string | undefined;
+export declare const resolveBaseUrl: (values: CliOptionValues, config: CliConfig, defaultBaseUrl: string, fail: CliFail) => string;
+export declare const normalizeBaseUrl: (value: string, fail: CliFail) => string;
+export declare const parseIntegerOption: ({ value, optionName, min, max, defaultValue, }: {
+    value: string | undefined;
+    optionName: string;
+    min: number;
+    max: number;
+    defaultValue: number;
+}, fail: CliFail) => number;
+export {};

package/dist/cli-options.js

@@ -0,0 +1,101 @@
+import { HISTORY_METRIC_ALIASES } from './history-response.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;
+};
+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');
+    }
+    return Array.from(new Set(candidates.map(value => normalizeAsin(value, 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');
+    }
+    return asins[0];
+};
+export const resolveHistoryMetrics = (values, fail) => {
+    const requested = (values.metrics ?? process.env.RR_HISTORY_METRICS ?? 'bsr,price')
+        .split(',')
+        .map(value => value.trim().toLowerCase())
+        .filter(Boolean);
+    if (requested.length === 0) {
+        fail('INVALID_INPUT', 'metrics cannot be empty');
+    }
+    const invalid = requested.filter(value => !HISTORY_METRIC_ALIASES.includes(value));
+    if (invalid.length > 0) {
+        fail('INVALID_INPUT', `unsupported history metric: ${invalid[0]}`, {
+            supportedMetrics: HISTORY_METRIC_ALIASES,
+        });
+    }
+    return Array.from(new Set(requested));
+};
+export const resolveHistoryWindow = (values, fail) => {
+    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');
+    }
+    return {
+        ...(startAt ? { startAt } : {}),
+        ...(endAt ? { endAt } : {}),
+        days: parseIntegerOption({
+            value: values.days,
+            optionName: 'days',
+            min: 30,
+            max: 3650,
+            defaultValue: 365,
+        }, fail),
+    };
+};
+export const resolveApiKey = () => {
+    return process.env.RR_LICENSE_KEY;
+};
+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, '');
+    if (!normalized) {
+        fail('INVALID_INPUT', 'base url cannot be empty');
+    }
+    return normalized;
+};
+export const parseIntegerOption = ({ value, optionName, min, max, defaultValue, }, fail) => {
+    if (!value) {
+        return defaultValue;
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed < min || parsed > max) {
+        fail('INVALID_INPUT', `${optionName} must be an integer between ${min} and ${max}`);
+    }
+    return parsed;
+};
+const normalizeDateOption = (optionName, value, fail) => {
+    const parsed = new Date(value);
+    if (!Number.isFinite(parsed.getTime())) {
+        fail('INVALID_INPUT', `${optionName} must be a valid date`);
+    }
+    return parsed.toISOString();
+};
+const normalizeAsin = (value, fail) => {
+    const normalized = value.trim().toUpperCase();
+    if (!ASIN_REGEX.test(normalized)) {
+        fail('INVALID_INPUT', `invalid ASIN: ${value}`);
+    }
+    return normalized;
+};
+const resolveEnvAsins = () => {
+    return [
+        ...(process.env.RR_ASINS ? process.env.RR_ASINS.split(',') : []),
+        ...(process.env.RR_ASIN ? [process.env.RR_ASIN] : []),
+    ];
+};

package/dist/cli-output.d.ts

@@ -0,0 +1,11 @@
+export declare const printSuccess: <T>(data: T) => void;
+export declare const fail: (code: string, message: string, details?: unknown) => never;
+export declare const resolveError: (error: unknown) => {
+    code: string;
+    message: string;
+    details: unknown;
+} | {
+    code: string;
+    message: string;
+    details?: undefined;
+};

package/dist/cli-output.js

@@ -0,0 +1,53 @@
+import { CliStorageError } from './cli-config.js';
+const OUTPUT_PRETTY = true;
+export const printSuccess = (data) => {
+    const envelope = {
+        ok: true,
+        data,
+    };
+    console.log(JSON.stringify(envelope, null, OUTPUT_PRETTY ? 2 : undefined));
+};
+export const fail = (code, message, details) => {
+    const envelope = {
+        ok: false,
+        error: {
+            code,
+            message,
+            ...(details !== undefined ? { details } : {}),
+        },
+    };
+    console.error(JSON.stringify(envelope, null, OUTPUT_PRETTY ? 2 : undefined));
+    process.exit(1);
+};
+export const resolveError = (error) => {
+    if (error instanceof CliStorageError) {
+        return {
+            code: error.code,
+            message: error.message,
+            details: error.details,
+        };
+    }
+    if (error && typeof error === 'object' && 'data' in error) {
+        const data = error.data;
+        if (data?.code) {
+            return {
+                code: data.code,
+                message: error instanceof Error ? error.message : 'Request failed',
+                details: data.httpStatus ? { httpStatus: data.httpStatus } : undefined,
+            };
+        }
+    }
+    if (error && typeof error === 'object' && 'message' in error) {
+        const message = error.message;
+        if (typeof message === 'string') {
+            return {
+                code: 'REQUEST_FAILED',
+                message,
+            };
+        }
+    }
+    return {
+        code: 'UNKNOWN_ERROR',
+        message: 'Unknown error',
+    };
+};

package/dist/history-response.d.ts

@@ -0,0 +1,41 @@
+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

@@ -0,0 +1,26 @@
+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;
+};

package/dist/index.js

@@ -1,18 +1,14 @@
 #!/usr/bin/env node
-import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
-import { homedir } from 'node:os';
-import path from 'node:path';
 import { parseArgs } from 'node:util';
 import { createRankWranglerClient, DEFAULT_API_BASE_URL } from '@rankwrangler/http-client';
-const ASIN_REGEX = /^[A-Z0-9]{10}$/i;
-const TRAILING_SLASHES_REGEX = /\/+$/;
-const API_SUFFIX_REGEX = /\/api$/i;
-const DEFAULT_MARKETPLACE_ID = 'ATVPDKIKX0DER';
-const CONFIG_DIR = path.join(homedir(), '.rankwrangler');
-const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
-const DEFAULT_OUTPUT_PRETTY = true;
+import { clearConfig, loadCliContext, loadCliPathsOrDefault, saveConfig, switchStorageDir, } from './cli-config.js';
+import { normalizeBaseUrl, parseIntegerOption, requireAsins, requireMarketplaceId, requireSingleAsin, resolveApiKey, resolveBaseUrl, resolveHistoryMetrics, resolveHistoryWindow, } from './cli-options.js';
+import { fail, printSuccess, resolveError } from './cli-output.js';
+import { buildCliHistoryResponse } from './history-response.js';
+import { printUsage } from './usage.js';
 const SUPPORTED_COMMANDS = new Set([
     'products:get',
+    'products:history',
     'license:status',
     'license:validate',
     'config:show',
@@ -23,56 +19,57 @@ const { positionals, values } = parseArgs({
     args: process.argv.slice(2),
     options: {
         help: { type: 'boolean', short: 'h' },
-        apiKey: { type: 'string' },
         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' },
+        limit: { type: 'string' },
     },
     allowPositionals: true,
 });
-const outputPretty = DEFAULT_OUTPUT_PRETTY;
 const main = async () => {
+    const optionValues = values;
     if (values.help || positionals.length === 0) {
-        printUsage();
+        printUsage(await loadCliPathsOrDefault());
         process.exit(values.help ? 0 : 1);
     }
-    const command = resolveCommand(positionals);
-    if (!command) {
-        fail('UNKNOWN_COMMAND', 'Unknown command', { command: positionals.join(' ') });
-        return;
-    }
+    const command = resolveCommandOrFail(positionals);
     if (!isSupportedCommand(command)) {
-        fail('UNKNOWN_COMMAND', 'Unknown command', { command: `${command.resource} ${command.verb}` });
-        return;
+        fail('UNKNOWN_COMMAND', 'Unknown command', {
+            command: `${command.resource} ${command.verb}`,
+        });
     }
-    const config = await loadConfig();
+    const { config, paths } = await loadCliContext();
     if (command.resource === 'config') {
-        const response = await runConfigCommand(command, config);
-        printSuccess(response);
+        printSuccess(await runConfigCommand(command, config, paths));
         return;
     }
-    const apiKey = resolveApiKey(config);
+    const apiKey = resolveApiKey();
     if (!apiKey) {
-        fail('MISSING_CONFIG', 'api key is required. set via `config set api-key <value>`');
-        return;
+        fail('MISSING_CONFIG', 'api key is required. set RR_LICENSE_KEY');
     }
-    const baseUrl = resolveBaseUrl(config);
     const client = createRankWranglerClient({
-        baseUrl,
+        baseUrl: resolveBaseUrl(optionValues, config, DEFAULT_API_BASE_URL, fail),
         apiKey,
     });
-    const response = await runApiCommand(command, client, config);
-    printSuccess(response);
+    printSuccess(await runApiCommand(command, client, config));
 };
 const runApiCommand = async (command, client, config) => {
     if (command.resource === 'products' && command.verb === 'get') {
-        const marketplaceId = requireMarketplaceId(config);
-        const asins = requireAsins(command.args);
+        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);
+    }
     if (command.resource === 'license' && command.verb === 'status') {
         return client.license.status.mutate();
     }
@@ -82,102 +79,88 @@ const runApiCommand = async (command, client, config) => {
     fail('UNKNOWN_COMMAND', 'Unknown command', {
         command: `${command.resource} ${command.verb}`,
     });
-    return null;
 };
-const runConfigCommand = async (command, config) => {
+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 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',
+        limit,
+        ...historyWindow,
+    });
+    return buildCliHistoryResponse({
+        asin,
+        marketplaceId,
+        metrics,
+        response: response,
+    });
+};
+const runConfigCommand = async (command, config, paths) => {
     if (command.verb === 'show') {
-        return {
-            path: CONFIG_PATH,
-            config,
-        };
+        return buildConfigResponse(paths, config);
     }
     if (command.verb === 'clear') {
-        await rm(CONFIG_PATH, { force: true });
+        await clearConfig(paths);
         return {
-            path: CONFIG_PATH,
+            ...buildConfigResponse(paths, {}),
             cleared: true,
         };
     }
-    if (command.verb === 'set') {
-        const [key, ...valueParts] = command.args;
-        if (!key || valueParts.length === 0) {
-            fail('INVALID_INPUT', 'config set requires <key> <value>');
-            return null;
-        }
-        const value = valueParts.join(' ').trim();
-        if (!value) {
-            fail('INVALID_INPUT', 'config set value cannot be empty');
-            return null;
-        }
-        const nextConfig = { ...config };
-        if (key === 'api-key') {
-            nextConfig.apiKey = value;
-        }
-        else if (key === 'base-url') {
-            nextConfig.baseUrl = normalizeBaseUrl(value);
-        }
-        else if (key === 'marketplace') {
-            nextConfig.marketplaceId = value;
-        }
-        else {
-            fail('INVALID_INPUT', 'unsupported config key', {
-                key,
-                supportedKeys: ['api-key', 'base-url', 'marketplace'],
-            });
-            return null;
-        }
-        await saveConfig(nextConfig);
-        return {
-            path: CONFIG_PATH,
-            config: nextConfig,
-        };
+    if (command.verb !== 'set') {
+        fail('UNKNOWN_COMMAND', 'Unknown config command', { verb: command.verb });
     }
-    fail('UNKNOWN_COMMAND', 'Unknown config command', { verb: command.verb });
-    return null;
-};
-const requireMarketplaceId = (config) => {
-    const marketplaceId = values.marketplace ?? config.marketplaceId ?? process.env.RR_MARKETPLACE_ID ?? DEFAULT_MARKETPLACE_ID;
-    return marketplaceId;
-};
-const requireAsins = (commandArgs) => {
-    const candidates = collectAsinCandidates(commandArgs);
-    if (candidates.length === 0) {
-        fail('INVALID_INPUT', 'at least one asin is required');
+    const [key, ...valueParts] = command.args;
+    if (!key || valueParts.length === 0) {
+        fail('INVALID_INPUT', 'config set requires <key> <value>');
     }
-    return Array.from(new Set(candidates.map(normalizeAsin)));
-};
-const collectAsinCandidates = (commandArgs) => {
-    const optionAsins = [...(values.asin ?? [])];
-    const envAsins = process.env.RR_ASINS
-        ? process.env.RR_ASINS.split(',').map(value => value.trim())
-        : [];
-    const envSingleAsin = process.env.RR_ASIN ? [process.env.RR_ASIN] : [];
-    return [...commandArgs, ...optionAsins, ...envAsins, ...envSingleAsin]
-        .map(value => value.trim())
-        .filter(Boolean);
-};
-const normalizeAsin = (value) => {
-    const normalized = value.trim().toUpperCase();
-    if (!ASIN_REGEX.test(normalized)) {
-        fail('INVALID_INPUT', `invalid ASIN: ${value}`);
+    const value = valueParts.join(' ').trim();
+    if (!value) {
+        fail('INVALID_INPUT', 'config set value cannot be empty');
     }
-    return normalized;
-};
-const resolveApiKey = (config) => {
-    return values.apiKey ?? config.apiKey ?? process.env.RR_LICENSE_KEY;
-};
-const resolveBaseUrl = (config) => {
-    const configured = values.baseUrl ?? config.baseUrl ?? process.env.RR_API_URL;
-    return normalizeBaseUrl(configured ?? DEFAULT_API_BASE_URL);
-};
-const normalizeBaseUrl = (value) => {
-    const trimmed = value.trim();
-    const withoutTrailingSlashes = trimmed.replace(TRAILING_SLASHES_REGEX, '');
-    const withoutApiSuffix = withoutTrailingSlashes.replace(API_SUFFIX_REGEX, '');
-    if (!withoutApiSuffix) {
-        fail('INVALID_INPUT', 'base url cannot be empty');
+    if (key === 'storage-dir') {
+        const nextState = await switchStorageDir({
+            currentConfig: config,
+            currentPaths: paths,
+            requestedStorageDir: value,
+        });
+        return buildConfigResponse(nextState.paths, nextState.config);
+    }
+    const nextConfig = { ...config };
+    if (key === 'base-url') {
+        nextConfig.baseUrl = normalizeBaseUrl(value, fail);
     }
-    return withoutApiSuffix;
+    else if (key === 'marketplace') {
+        nextConfig.marketplaceId = value;
+    }
+    else {
+        fail('INVALID_INPUT', 'unsupported config key', {
+            key,
+            supportedKeys: ['base-url', 'marketplace', 'storage-dir'],
+        });
+    }
+    await saveConfig(paths, nextConfig);
+    return buildConfigResponse(paths, nextConfig);
+};
+const buildConfigResponse = (paths, config) => {
+    return {
+        storageDir: paths.storageDir,
+        path: paths.configPath,
+        globalPath: paths.globalConfigPath,
+        config,
+    };
 };
 const resolveCommand = (inputPositionals) => {
     const [first, second, ...rest] = inputPositionals;
@@ -190,121 +173,16 @@ const resolveCommand = (inputPositionals) => {
         args: rest,
     };
 };
-const isSupportedCommand = (command) => {
-    return SUPPORTED_COMMANDS.has(`${command.resource}:${command.verb}`);
-};
-const loadConfig = async () => {
-    try {
-        const raw = await readFile(CONFIG_PATH, 'utf8');
-        const parsed = JSON.parse(raw);
-        return {
-            apiKey: typeof parsed.apiKey === 'string' ? parsed.apiKey : undefined,
-            baseUrl: typeof parsed.baseUrl === 'string' ? normalizeBaseUrl(parsed.baseUrl) : undefined,
-            marketplaceId: typeof parsed.marketplaceId === 'string' ? parsed.marketplaceId : undefined,
-        };
+const resolveCommandOrFail = (inputPositionals) => {
+    const command = resolveCommand(inputPositionals);
+    if (command) {
+        return command;
     }
-    catch (error) {
-        if (error &&
-            typeof error === 'object' &&
-            'code' in error &&
-            error.code === 'ENOENT') {
-            return {};
-        }
-        fail('INVALID_CONFIG', 'failed to read config', { path: CONFIG_PATH });
-        return {};
-    }
-};
-const saveConfig = async (config) => {
-    await mkdir(CONFIG_DIR, { recursive: true });
-    await writeFile(CONFIG_PATH, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+    fail('UNKNOWN_COMMAND', 'Unknown command', { command: inputPositionals.join(' ') });
+    throw new Error('unreachable');
 };
-const resolveError = (error) => {
-    if (error && typeof error === 'object') {
-        if ('data' in error) {
-            const data = error.data;
-            if (data?.code) {
-                return {
-                    code: data.code,
-                    message: error instanceof Error
-                        ? error.message
-                        : 'Request failed',
-                    details: data.httpStatus ? { httpStatus: data.httpStatus } : undefined,
-                };
-            }
-        }
-        if ('message' in error && typeof error.message === 'string') {
-            return {
-                code: 'REQUEST_FAILED',
-                message: error.message,
-            };
-        }
-    }
-    return {
-        code: 'UNKNOWN_ERROR',
-        message: 'Unknown error',
-    };
-};
-const printSuccess = (data) => {
-    const envelope = {
-        ok: true,
-        data,
-    };
-    console.log(JSON.stringify(envelope, null, outputPretty ? 2 : undefined));
-};
-const fail = (code, message, details) => {
-    const envelope = {
-        ok: false,
-        error: {
-            code,
-            message,
-            ...(details !== undefined ? { details } : {}),
-        },
-    };
-    console.error(JSON.stringify(envelope, null, outputPretty ? 2 : undefined));
-    process.exit(1);
-};
-const printUsage = () => {
-    const usage = [
-        'NAME',
-        '  rw, rankwrangler - RankWrangler command line interface',
-        '',
-        'SYNOPSIS',
-        '  rw <resource> <verb> [args...] [options]',
-        '  rankwrangler <resource> <verb> [args...] [options]',
-        '',
-        'COMMANDS',
-        '  products get <ASIN...>',
-        '  license status',
-        '  license validate',
-        '  config show',
-        '  config clear',
-        '  config set api-key <value>',
-        '  config set base-url <origin>',
-        '  config set marketplace <marketplaceId>',
-        '',
-        'OPTIONS',
-        '  -h, --help               Show this help message',
-        '  --apiKey <value>         Override API key',
-        '  --baseUrl <origin>       Override API origin',
-        `  -m, --marketplace <id>   Override marketplace (default: ${DEFAULT_MARKETPLACE_ID})`,
-        '  --asin <ASIN>            Add ASIN (repeatable)',
-        '',
-        'FILES',
-        `  ${CONFIG_PATH}           Local CLI config`,
-        '',
-        'ENVIRONMENT',
-        '  RR_LICENSE_KEY           API key fallback',
-        '  RR_API_URL               API origin fallback',
-        '  RR_MARKETPLACE_ID        Marketplace fallback',
-        '  RR_ASIN                  Single ASIN fallback',
-        '  RR_ASINS                 Comma-separated ASIN fallback',
-        '',
-        'EXAMPLES',
-        '  rw config set api-key rrk_...',
-        '  rw products get B0DV53VS61',
-        '  rankwrangler license status',
-    ];
-    console.log(usage.join('\n'));
+const isSupportedCommand = (command) => {
+    return SUPPORTED_COMMANDS.has(`${command.resource}:${command.verb}`);
 };
 await main().catch(error => {
     const resolved = resolveError(error);

package/dist/usage.d.ts

@@ -0,0 +1,2 @@
+import type { CliPaths } from './cli-config';
+export declare const printUsage: (paths: CliPaths) => void;

package/dist/usage.js

@@ -0,0 +1,55 @@
+const DEFAULT_MARKETPLACE_ID = 'ATVPDKIKX0DER';
+export const printUsage = (paths) => {
+    const usage = [
+        'NAME',
+        '  rw, rankwrangler - RankWrangler command line interface',
+        '',
+        'SYNOPSIS',
+        '  rw <resource> <verb> [args...] [options]',
+        '  rankwrangler <resource> <verb> [args...] [options]',
+        '',
+        'COMMANDS',
+        '  products get <ASIN...>',
+        '  products history <ASIN>',
+        '  license status',
+        '  license validate',
+        '  config show',
+        '  config clear',
+        '  config set base-url <origin>',
+        '  config set marketplace <marketplaceId>',
+        '  config set storage-dir <path>',
+        '',
+        'OPTIONS',
+        '  -h, --help               Show this help message',
+        '  --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)',
+        '  --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>              Max points per metric (1-10000, default: 5000)',
+        '',
+        'FILES',
+        `  ${paths.configPath}           Active CLI config`,
+        `  ${paths.globalConfigPath}           Global CLI settings`,
+        '',
+        'ENVIRONMENT',
+        '  RR_LICENSE_KEY           API key source',
+        '  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',
+        '',
+        'EXAMPLES',
+        '  RR_LICENSE_KEY=rrk_... rw products get B0DV53VS61',
+        '  RR_STORAGE_DIR=~/.config/rankwrangler rw config show',
+        '  rw config set storage-dir ~/.config/rankwrangler',
+        '  rw products history B0DV53VS61 --metrics bsr,price',
+        '  rw products history B0DV53VS61 --startAt 2025-01-01 --endAt 2025-12-31',
+        '  rankwrangler license status',
+    ];
+    console.log(usage.join('\n'));
+};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rankwrangler/cli",
-    "version": "0.2.2",
+    "version": "0.4.0",
     "description": "Official RankWrangler command line interface",
     "type": "module",
     "bin": {
@@ -14,13 +14,14 @@
         "README.md"
     ],
     "scripts": {
-        "build": "tsc -p tsconfig.json"
+        "build": "tsc -p tsconfig.json && node scripts/fix-dist-imports.mjs",
+        "test:e2e": "bun test test/index.e2e.test.ts"
     },
     "publishConfig": {
         "access": "public"
     },
     "dependencies": {
-        "@rankwrangler/http-client": "^0.2.2"
+        "@rankwrangler/http-client": "^0.4.0"
     },
     "devDependencies": {
         "@types/node": "^24.3.0",