@rankwrangler/cli 0.4.1 → 0.5.0

package/README.md

@@ -11,19 +11,24 @@ npm install -g @rankwrangler/cli
 ## Usage
 
 ```bash
-export RR_LICENSE_KEY=rrk_...
 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
 ```
 
-`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.
+`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.
 

package/dist/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to this project will be documented in this file.
 
+## v0.5.0 - 2026-03-18
+
+### Added
+
+- Add CLI secure-store auth with `rw auth set`, `rw auth status`, and `rw auth clear`, storing
+  license keys in the platform secure store while keeping `RR_LICENSE_KEY` as an override for
+  CI, automation, and agent runtimes.
+
+### Changed
+
+- Change local development defaults so the app server no longer starts the job runner unless you
+  use the explicit jobs-enabled dev commands.
+
+### Fixed
+
+- Fix top search terms scheduler timestamp handling so due datasets are selected and refreshed
+  reliably.
+
 ## v0.4.1 - 2026-03-09
 
 ### Added

package/dist/cli-auth.d.ts

@@ -0,0 +1,86 @@
+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";
+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);
+}
+export declare const resolveApiKey: () => Promise<string | undefined>;
+export declare const runAuthCommand: (command: AuthCommand, fail: CliFail) => Promise<{
+    source: string;
+    envOverride: boolean;
+    secureStore: {
+        backend: string;
+        serviceName: string;
+        accountName: string;
+        available: boolean;
+        hasStoredLicenseKey: boolean;
+        error?: undefined;
+    };
+} | {
+    source: string;
+    envOverride: boolean;
+    secureStore: {
+        backend: string;
+        serviceName: string;
+        accountName: string;
+        available: boolean;
+        hasStoredLicenseKey: null;
+        error: string;
+    };
+} | {
+    saved: boolean;
+    source: string;
+    envOverride: boolean;
+    secureStore: {
+        backend: string;
+        serviceName: string;
+        accountName: string;
+        available: boolean;
+        hasStoredLicenseKey: boolean;
+        error?: undefined;
+    };
+} | {
+    saved: boolean;
+    source: string;
+    envOverride: boolean;
+    secureStore: {
+        backend: string;
+        serviceName: string;
+        accountName: string;
+        available: boolean;
+        hasStoredLicenseKey: null;
+        error: string;
+    };
+} | {
+    cleared: boolean;
+    source: string;
+    envOverride: boolean;
+    secureStore: {
+        backend: string;
+        serviceName: string;
+        accountName: string;
+        available: boolean;
+        hasStoredLicenseKey: boolean;
+        error?: undefined;
+    };
+} | {
+    cleared: boolean;
+    source: string;
+    envOverride: boolean;
+    secureStore: {
+        backend: string;
+        serviceName: string;
+        accountName: string;
+        available: boolean;
+        hasStoredLicenseKey: null;
+        error: string;
+    };
+}>;
+export {};

package/dist/cli-auth.js

@@ -0,0 +1,171 @@
+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';
+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 secureStore = await createSecureStore();
+    return (await secureStore.get()) ?? undefined;
+};
+export const runAuthCommand = async (command, fail) => {
+    if (command.verb === 'status') {
+        return buildAuthStatus();
+    }
+    if (command.verb === 'set') {
+        const value = resolveAuthSetValue(command.args, fail);
+        const secureStore = await createSecureStore();
+        await secureStore.set(value);
+        return {
+            ...(await buildAuthStatus()),
+            saved: true,
+        };
+    }
+    if (command.verb === 'clear') {
+        const secureStore = await createSecureStore();
+        const cleared = await secureStore.clear();
+        return {
+            ...(await buildAuthStatus()),
+            cleared,
+        };
+    }
+    fail('UNKNOWN_COMMAND', 'Unknown auth command', { verb: command.verb });
+};
+const buildAuthStatus = async () => {
+    const envLicenseKey = resolveEnvLicenseKey();
+    try {
+        const secureStore = await createSecureStore();
+        const storedLicenseKey = await secureStore.get();
+        return {
+            source: envLicenseKey ? 'env' : storedLicenseKey ? 'secure-store' : 'none',
+            envOverride: Boolean(envLicenseKey),
+            secureStore: {
+                backend: secureStore.backend,
+                serviceName: secureStore.serviceName,
+                accountName: secureStore.accountName,
+                available: true,
+                hasStoredLicenseKey: Boolean(storedLicenseKey),
+            },
+        };
+    }
+    catch (error) {
+        return {
+            source: envLicenseKey ? 'env' : 'none',
+            envOverride: Boolean(envLicenseKey),
+            secureStore: {
+                backend: getSecureStoreBackendLabel(),
+                serviceName: AUTH_SERVICE_NAME,
+                accountName: AUTH_ACCOUNT_NAME,
+                available: false,
+                hasStoredLicenseKey: null,
+                error: error instanceof Error ? error.message : 'Unknown secure-store error',
+            },
+        };
+    }
+};
+const resolveAuthSetValue = (args, fail) => {
+    const positionalValue = args.join(' ').trim();
+    if (positionalValue) {
+        return positionalValue;
+    }
+    const envLicenseKey = resolveEnvLicenseKey();
+    if (envLicenseKey) {
+        return envLicenseKey;
+    }
+    fail('INVALID_INPUT', `auth set requires <licenseKey> or ${LICENSE_KEY_ENV_VAR}`);
+};
+const resolveEnvLicenseKey = () => {
+    const value = process.env[LICENSE_KEY_ENV_VAR]?.trim();
+    return value ? value : undefined;
+};
+const createSecureStore = async () => {
+    const internalSecretStoreDir = process.env[INTERNAL_SECRET_STORE_DIR_ENV_VAR]?.trim();
+    if (internalSecretStoreDir) {
+        return createFileSecretStore(path.resolve(internalSecretStoreDir));
+    }
+    const keytar = await loadKeytar();
+    return {
+        backend: getSecureStoreBackendLabel(),
+        serviceName: AUTH_SERVICE_NAME,
+        accountName: AUTH_ACCOUNT_NAME,
+        get: () => keytar.getPassword(AUTH_SERVICE_NAME, AUTH_ACCOUNT_NAME),
+        set: value => keytar.setPassword(AUTH_SERVICE_NAME, AUTH_ACCOUNT_NAME, value),
+        clear: () => keytar.deletePassword(AUTH_SERVICE_NAME, AUTH_ACCOUNT_NAME),
+    };
+};
+const loadKeytar = async () => {
+    try {
+        const imported = (await import('keytar'));
+        return imported.default ?? imported;
+    }
+    catch (error) {
+        throw new CliAuthError('SECURE_STORE_UNAVAILABLE', 'platform secure store is unavailable', error instanceof Error ? { cause: error.message } : undefined);
+    }
+};
+const getSecureStoreBackendLabel = () => {
+    switch (process.platform) {
+        case 'darwin':
+            return 'macos-keychain';
+        case 'win32':
+            return 'windows-credential-manager';
+        default:
+            return 'platform-secure-store';
+    }
+};
+const createFileSecretStore = (secretStoreDir) => {
+    const secretPath = path.join(secretStoreDir, 'license-key.json');
+    return {
+        backend: 'test-file-store',
+        serviceName: AUTH_SERVICE_NAME,
+        accountName: AUTH_ACCOUNT_NAME,
+        get: async () => {
+            try {
+                const raw = await readFile(secretPath, 'utf8');
+                const parsed = JSON.parse(raw);
+                return typeof parsed.licenseKey === 'string' ? parsed.licenseKey : null;
+            }
+            catch (error) {
+                if (error &&
+                    typeof error === 'object' &&
+                    'code' in error &&
+                    error.code === 'ENOENT') {
+                    return null;
+                }
+                throw new CliAuthError('INVALID_CONFIG', 'failed to read secure-store test data');
+            }
+        },
+        set: async (value) => {
+            await mkdir(secretStoreDir, { recursive: true });
+            await writeFile(secretPath, `${JSON.stringify({ licenseKey: value }, null, 2)}\n`, 'utf8');
+        },
+        clear: async () => {
+            try {
+                await rm(secretPath);
+                return true;
+            }
+            catch (error) {
+                if (error &&
+                    typeof error === 'object' &&
+                    'code' in error &&
+                    error.code === 'ENOENT') {
+                    return false;
+                }
+                throw error;
+            }
+        },
+    };
+};

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

@@ -0,0 +1,19 @@
+import { type CliConfig, type CliPaths } from './cli-config';
+type CliFail = (code: string, message: string, details?: unknown) => never;
+type ConfigCommand = {
+    verb: string;
+    args: string[];
+};
+export declare const runConfigCommand: (command: ConfigCommand, config: CliConfig, paths: CliPaths, fail: CliFail) => Promise<{
+    storageDir: string;
+    path: string;
+    globalPath: string;
+    config: CliConfig;
+} | {
+    cleared: boolean;
+    storageDir: string;
+    path: string;
+    globalPath: string;
+    config: CliConfig;
+}>;
+export {};

package/dist/cli-config-command.js

@@ -0,0 +1,56 @@
+import { clearConfig, saveConfig, switchStorageDir } from './cli-config.js';
+import { normalizeBaseUrl } from './cli-options.js';
+export const runConfigCommand = async (command, config, paths, fail) => {
+    if (command.verb === 'show') {
+        return buildConfigResponse(paths, config);
+    }
+    if (command.verb === 'clear') {
+        await clearConfig(paths);
+        return {
+            ...buildConfigResponse(paths, {}),
+            cleared: true,
+        };
+    }
+    if (command.verb !== 'set') {
+        fail('UNKNOWN_COMMAND', 'Unknown config command', { verb: command.verb });
+    }
+    const [key, ...valueParts] = command.args;
+    if (!key || valueParts.length === 0) {
+        fail('INVALID_INPUT', 'config set requires <key> <value>');
+    }
+    const value = valueParts.join(' ').trim();
+    if (!value) {
+        fail('INVALID_INPUT', 'config set value 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);
+    }
+    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,
+    };
+};

package/dist/cli-options.d.ts

@@ -22,7 +22,6 @@ export declare const resolveHistoryWindow: (values: CliOptionValues, fail: CliFa
     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, }: {

package/dist/cli-options.js

@@ -56,9 +56,6 @@ export const resolveHistoryWindow = (values, fail) => {
         }, 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);
 };

package/dist/cli-output.js

@@ -1,3 +1,4 @@
+import { CliAuthError } from './cli-auth.js';
 import { CliStorageError } from './cli-config.js';
 const OUTPUT_PRETTY = true;
 export const printSuccess = (data) => {
@@ -27,6 +28,13 @@ export const resolveError = (error) => {
             details: error.details,
         };
     }
+    if (error instanceof CliAuthError) {
+        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) {

package/dist/index.js

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
 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 { clearConfig, loadCliContext, loadCliPathsOrDefault, saveConfig, switchStorageDir, } from './cli-config.js';
-import { normalizeBaseUrl, parseIntegerOption, requireAsins, requireMarketplaceId, requireSingleAsin, resolveApiKey, resolveBaseUrl, resolveHistoryMetrics, resolveHistoryWindow, } from './cli-options.js';
+import { runConfigCommand } from './cli-config-command.js';
+import { loadCliContext, loadCliPathsOrDefault } from './cli-config.js';
+import { parseIntegerOption, requireAsins, requireMarketplaceId, requireSingleAsin, 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';
@@ -12,6 +14,9 @@ const SUPPORTED_COMMANDS = new Set([
     'products:history',
     'license:status',
     'license:validate',
+    'auth:status',
+    'auth:set',
+    'auth:clear',
     'config:show',
     'config:clear',
     'config:set',
@@ -57,12 +62,16 @@ const main = async () => {
     }
     const { config, paths } = await loadCliContext();
     if (command.resource === 'config') {
-        printSuccess(await runConfigCommand(command, config, paths));
+        printSuccess(await runConfigCommand(command, config, paths, fail));
         return;
     }
-    const apiKey = resolveApiKey();
+    if (command.resource === 'auth') {
+        printSuccess(await runAuthCommand(command, fail));
+        return;
+    }
+    const apiKey = await resolveApiKey();
     if (!apiKey) {
-        fail('MISSING_CONFIG', 'api key is required. set RR_LICENSE_KEY');
+        fail('MISSING_CONFIG', 'license key is required. run `rw auth set <licenseKey>` or set RR_LICENSE_KEY');
     }
     const client = createRankWranglerClient({
         baseUrl: resolveBaseUrl(optionValues, config, DEFAULT_API_BASE_URL, fail),
@@ -121,60 +130,6 @@ const runProductHistoryCommand = async (command, client, config) => {
         response: response,
     });
 };
-const runConfigCommand = async (command, config, paths) => {
-    if (command.verb === 'show') {
-        return buildConfigResponse(paths, config);
-    }
-    if (command.verb === 'clear') {
-        await clearConfig(paths);
-        return {
-            ...buildConfigResponse(paths, {}),
-            cleared: true,
-        };
-    }
-    if (command.verb !== 'set') {
-        fail('UNKNOWN_COMMAND', 'Unknown config command', { verb: command.verb });
-    }
-    const [key, ...valueParts] = command.args;
-    if (!key || valueParts.length === 0) {
-        fail('INVALID_INPUT', 'config set requires <key> <value>');
-    }
-    const value = valueParts.join(' ').trim();
-    if (!value) {
-        fail('INVALID_INPUT', 'config set value 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);
-    }
-    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 resolveMetaCommand = (inputPositionals) => {
     if (inputPositionals.length === 1 && inputPositionals[0] === 'changelog') {
         return { name: 'changelog' };

package/dist/usage.js

@@ -1,3 +1,4 @@
+import { LICENSE_KEY_ENV_VAR } from './cli-auth.js';
 const DEFAULT_MARKETPLACE_ID = 'ATVPDKIKX0DER';
 export const printUsage = (paths) => {
     const usage = [
@@ -18,6 +19,9 @@ export const printUsage = (paths) => {
         '  products history <ASIN>',
         '  license status',
         '  license validate',
+        '  auth status',
+        '  auth set <licenseKey>',
+        '  auth clear',
         '  config show',
         '  config clear',
         '  config set base-url <origin>',
@@ -41,7 +45,7 @@ export const printUsage = (paths) => {
         `  ${paths.globalConfigPath}           Global CLI settings`,
         '',
         'ENVIRONMENT',
-        '  RR_LICENSE_KEY           API key source',
+        `  ${LICENSE_KEY_ENV_VAR}           License key override for CI/automation`,
         '  RR_API_URL               API origin fallback',
         '  RR_MARKETPLACE_ID        Marketplace fallback',
         '  RR_STORAGE_DIR           Storage directory override',
@@ -50,7 +54,8 @@ export const printUsage = (paths) => {
         '  RR_HISTORY_METRICS       Comma-separated history metrics fallback',
         '',
         'EXAMPLES',
-        '  RR_LICENSE_KEY=rrk_... rw products get B0DV53VS61',
+        '  rw auth set rrk_...',
+        `  ${LICENSE_KEY_ENV_VAR}=rrk_... rw products get B0DV53VS61`,
         '  RR_STORAGE_DIR=~/.config/rankwrangler rw config show',
         '  rw --version',
         '  rw changelog',

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rankwrangler/cli",
-    "version": "0.4.1",
+    "version": "0.5.0",
     "description": "Official RankWrangler command line interface",
     "type": "module",
     "bin": {
@@ -23,7 +23,8 @@
         "access": "public"
     },
     "dependencies": {
-        "@rankwrangler/http-client": "^0.4.1"
+        "@rankwrangler/http-client": "^0.5.0",
+        "keytar": "^7.9.0"
     },
     "devDependencies": {
         "@types/node": "^24.3.0",