@rankwrangler/cli 0.1.2

package/README.md

@@ -0,0 +1,37 @@
+# @rankwrangler/cli
+
+Official CLI for RankWrangler.
+
+## Install
+
+```bash
+npm install -g @rankwrangler/cli
+```
+
+## Usage
+
+```bash
+rankwrangler config set api-key rrk_...
+rankwrangler products get B0DV53VS61
+```
+
+## Development
+
+```bash
+bun run cli:build
+```
+
+## Release (Maintainers)
+
+```bash
+cd packages/cli
+set -a
+source ../../.env
+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/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,318 @@
+#!/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;
+const { positionals, values } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+        help: { type: 'boolean', short: 'h' },
+        apiKey: { type: 'string' },
+        licenseKey: { type: 'string' },
+        baseUrl: { type: 'string' },
+        url: { type: 'string' },
+        marketplace: { type: 'string', short: 'm' },
+        marketplaceId: { type: 'string' },
+        asin: { type: 'string', multiple: true },
+        asins: { type: 'string', multiple: true },
+    },
+    allowPositionals: true,
+});
+const outputPretty = DEFAULT_OUTPUT_PRETTY;
+const main = async () => {
+    if (values.help || positionals.length === 0) {
+        printUsage();
+        process.exit(values.help ? 0 : 1);
+    }
+    const command = resolveCommand(positionals);
+    if (!command) {
+        fail('UNKNOWN_COMMAND', 'Unknown command', { command: positionals.join(' ') });
+        return;
+    }
+    const config = await loadConfig();
+    if (command.resource === 'config') {
+        const response = await runConfigCommand(command, config);
+        printSuccess(response);
+        return;
+    }
+    const apiKey = resolveApiKey(config);
+    if (!apiKey) {
+        fail('MISSING_CONFIG', 'api key is required. set via `config set api-key <value>`');
+        return;
+    }
+    const baseUrl = resolveBaseUrl(config);
+    const client = createRankWranglerClient({
+        baseUrl,
+        apiKey,
+    });
+    const response = await runApiCommand(command, client, config);
+    printSuccess(response);
+};
+const runApiCommand = async (command, client, config) => {
+    if (command.resource === 'products' && command.verb === 'get') {
+        const marketplaceId = requireMarketplaceId(config);
+        const asins = requireAsins(command.args);
+        if (asins.length === 1) {
+            return client.getProductInfo.mutate({ marketplaceId, asin: asins[0] });
+        }
+        return client.getProductInfoBatch.mutate({ marketplaceId, asins });
+    }
+    if (command.resource === 'license' && command.verb === 'status') {
+        return client.license.status.mutate();
+    }
+    if (command.resource === 'license' && command.verb === 'validate') {
+        return client.license.validate.mutate();
+    }
+    fail('UNKNOWN_COMMAND', 'Unknown command', {
+        command: `${command.resource} ${command.verb}`,
+    });
+    return null;
+};
+const runConfigCommand = async (command, config) => {
+    if (command.verb === 'show') {
+        return {
+            path: CONFIG_PATH,
+            config,
+        };
+    }
+    if (command.verb === 'clear') {
+        await rm(CONFIG_PATH, { force: true });
+        return {
+            path: CONFIG_PATH,
+            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' || key === 'marketplace-id') {
+            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,
+        };
+    }
+    fail('UNKNOWN_COMMAND', 'Unknown config command', { verb: command.verb });
+    return null;
+};
+const requireMarketplaceId = (config) => {
+    const marketplaceId = values.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');
+    }
+    return Array.from(new Set(candidates.map(normalizeAsin)));
+};
+const collectAsinCandidates = (commandArgs) => {
+    const optionAsins = [...(values.asin ?? []), ...(values.asins ?? [])];
+    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}`);
+    }
+    return normalized;
+};
+const resolveApiKey = (config) => {
+    return values.apiKey ?? values.licenseKey ?? config.apiKey ?? process.env.RR_LICENSE_KEY;
+};
+const resolveBaseUrl = (config) => {
+    const configured = values.baseUrl ?? values.url ?? 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');
+    }
+    return withoutApiSuffix;
+};
+const resolveCommand = (inputPositionals) => {
+    const [first, second, ...rest] = inputPositionals;
+    if (!first) {
+        return null;
+    }
+    if (first === 'get-product-info') {
+        return {
+            resource: 'products',
+            verb: 'get',
+            args: rest,
+        };
+    }
+    if (first === 'get-product-info-batch') {
+        return {
+            resource: 'products',
+            verb: 'get',
+            args: rest,
+        };
+    }
+    if (!second) {
+        return null;
+    }
+    return {
+        resource: first,
+        verb: first === 'products' && second === 'get-batch' ? 'get' : second,
+        args: rest,
+    };
+};
+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,
+        };
+    }
+    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');
+};
+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 = [
+        'RankWrangler CLI',
+        '',
+        'Command Shape',
+        '  rankwrangler <resource> <verb> [args...] [flags...]',
+        '',
+        'Principles',
+        '  - Resource-first, verb-second commands',
+        '  - JSON-only output with {"ok": true|false, ...} envelope',
+        '  - One command maps to one API capability',
+        '',
+        'API Commands',
+        '  products get <ASIN...> [--marketplace <id>|-m <id>]',
+        '  license status',
+        '  license validate',
+        '',
+        'Config Commands',
+        '  config show',
+        '  config clear',
+        '  config set api-key <value>',
+        '  config set base-url <origin>',
+        '  config set marketplace <marketplaceId>',
+        '',
+        'Global Flags',
+        '  --apiKey <value>         Override API key (alias: --licenseKey)',
+        '  --baseUrl <origin>       Override API origin (alias: --url)',
+        `  --marketplace <id>, -m   Override marketplace (default: ${DEFAULT_MARKETPLACE_ID})`,
+        '  --marketplaceId <id>     Compatibility alias for --marketplace',
+        '  --asin <ASIN>            Add ASIN (repeatable)',
+        '  --asins <ASIN>           Add ASIN (repeatable, compatibility alias)',
+        '',
+        'Legacy Aliases (still supported)',
+        '  get-product-info',
+        '  get-product-info-batch',
+        '  products get-batch',
+    ];
+    console.log(usage.join('\n'));
+};
+await main().catch(error => {
+    const resolved = resolveError(error);
+    fail(resolved.code, resolved.message, resolved.details);
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+    "name": "@rankwrangler/cli",
+    "version": "0.1.2",
+    "description": "Official RankWrangler command line interface",
+    "type": "module",
+    "bin": {
+        "rankwrangler": "dist/index.js"
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "tsc -p tsconfig.json"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "dependencies": {
+        "@rankwrangler/http-client": "^0.1.2"
+    },
+    "devDependencies": {
+        "@types/node": "^24.3.0",
+        "typescript": "^5.9.2"
+    },
+    "packageManager": "bun@1.1.27"
+}