Merge pull request #2 from bitrefill/json-output

JSON output, output modules, tests, and CI

Author: marcopesani

.github/workflows/commit.yml

@@ -20,5 +20,7 @@ jobs:
               run: pnpm install --frozen-lockfile
             - name: Format
               run: pnpm format
+            - name: Test
+              run: pnpm test
             - name: Build
               run: pnpm build

.github/workflows/npm-publish.yml

@@ -21,5 +21,6 @@ jobs:
                   registry-url: 'https://registry.npmjs.org'
             - run: pnpm install --frozen-lockfile
             - run: pnpm format
+            - run: pnpm test
             - run: pnpm build
             - run: pnpm publish --provenance --access public --no-git-checks

README.md

@@ -34,10 +34,29 @@ bitrefill search-products --query "Netflix"
 cp .env.example .env
 ```
 
+Node does not load `.env` files automatically. After editing `.env`, either export variables in your shell (`set -a && source .env && set +a` in bash/zsh) or pass `--api-key` on the command line.
+
 ## Usage
 
 ```bash
-bitrefill [--api-key <key>] <command> [options]
+bitrefill [--api-key <key>] [--json] <command> [options]
+```
+
+### Human-readable output (default)
+
+Tool results are pretty-printed JSON on stdout. Status messages (OAuth prompts, etc.) also go to stdout.
+
+### Machine-readable output (`--json`)
+
+Pass `--json` anywhere before the subcommand so scripts and `jq` get a single JSON value per invocation on stdout:
+
+- **stdout**: Only the tool result (JSON). Text payloads from the server may be JSON or [TOON](https://toonformat.dev/); the CLI decodes TOON to JSON when needed.
+- **stderr**: Progress messages, errors, and client errors (JSON `{ "error": "..." }` for failures).
+
+Example:
+
+```bash
+bitrefill --json search-products --query "Amazon" --per_page 1 | jq '.products[0].name'
 ```
 
 ### Examples
@@ -62,6 +81,18 @@ bitrefill --help
 bitrefill logout
 ```
 
+## Development
+
+From the repository root (requires [pnpm](https://pnpm.io/)):
+
+```bash
+pnpm install
+pnpm format    # Prettier check
+pnpm test      # Vitest unit tests
+pnpm build     # Compile to dist/
+pnpm dev -- --help   # Run CLI via tsx without building
+```
+
 ## Paying
 
 **Flow:** `get-product-details` → pick `product_id` + `package_id` → `buy-products` with `--cart_items` and `--payment_method`.

package.json

@@ -10,7 +10,8 @@
     "build": "tsc",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",
-    "format": "prettier --check ./src"
+    "format": "prettier --check ./src",
+    "test": "vitest run"
   },
   "repository": {
     "type": "git",
@@ -22,13 +23,15 @@
   "packageManager": "pnpm@10.27.0",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
+    "@toon-format/toon": "^2.1.0",
     "commander": "^14.0.3"
   },
   "devDependencies": {
     "@types/node": "^25.3.0",
     "prettier": "^3.8.1",
     "tsx": "^4.21.0",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
   },
   "keywords": [
     "mcp",