@shreyassp002/pinionos-emulator 0.1.0

package/README.md

@@ -0,0 +1,171 @@
+<div align="center">
+
+# PinionOS Emulator
+
+**Local PinionOS-compatible backend for product development and testing**
+
+Test your app with the same `pinion-os` SDK calls, without real USDC spend.
+
+</div>
+
+## What This Project Is
+
+`pinionos-emulator` is a local server that mirrors Pinion skill APIs so teams can build and test products safely.
+
+Use it when you want to:
+- develop app flows without hitting production
+- run deterministic integration tests in CI
+- exercise x402/unlimited-key paths locally
+- inspect request/response behavior in a terminal dashboard
+
+## Pinion SDK Compatibility
+
+This emulator is designed for `pinion-os` client usage by pointing the SDK to local URL:
+
+```ts
+import { PinionClient } from 'pinion-os';
+
+const client = new PinionClient({
+  privateKey: process.env.PRIVATE_KEY!,
+  apiUrl: 'http://localhost:4020'
+});
+```
+
+## Supported SDK Skills
+
+| Skill | SDK Method | Emulator Endpoint | Status |
+|---|---|---|---|
+| balance | `skills.balance(address)` | `GET /balance/:address` | Supported |
+| tx | `skills.tx(hash)` | `GET /tx/:hash` | Supported |
+| price | `skills.price(token)` | `GET /price/:token` | Supported |
+| wallet | `skills.wallet()` | `GET /wallet/generate` | Supported |
+| chat | `skills.chat(message)` | `POST /chat` | Supported |
+| send | `skills.send(to, amount, token)` | `POST /send` | Supported |
+| trade | `skills.trade(src, dst, amount, slippage)` | `POST /trade` | Supported |
+| fund | `skills.fund(address)` | `GET /fund/:address` | Supported |
+| broadcast | `skills.broadcast(tx)` | `POST /broadcast` | Supported |
+| unlimited | `skills.unlimited()` | `POST /unlimited` | Supported |
+| unlimited-verify | `skills.unlimitedVerify(key)` | `GET /unlimited/verify?key=...` | Supported |
+
+## Supported MCP Tools
+
+Your emulator MCP server currently exposes:
+- `pinion_price`
+- `pinion_balance`
+- `pinion_wallet`
+- `pinion_tx`
+- `pinion_chat`
+- `pinion_send`
+- `pinion_trade`
+- `pinion_fund`
+- `pinion_broadcast`
+- `pinion_unlimited`
+- `pinion_unlimited_verify`
+- `pinion_pay_service`
+- `pinion_facilitator_verify`
+
+## Emulator Features Beyond Core Skills
+
+- x402 middleware mode (`--x402`) with 402 challenge flow
+- unlimited API key issuance and verification
+- generic x402 test service (`/x402/*`)
+- mock facilitator endpoints (`/facilitator/verify`, `/facilitator/status`)
+- request recording (`/recording/start`, `/recording/stop`, `/recording/status`)
+- chaos/error injection via config (`errorSimulation`)
+- mutable in-memory balances + reset (`POST /reset`)
+- terminal dashboard (feed, prices, wallet, inspector)
+
+## Quick Start
+
+```bash
+npm install
+npm start
+```
+
+Health check:
+
+```bash
+curl -s http://localhost:4020/health | jq
+```
+
+Headless mode:
+
+```bash
+npx pinionos-emulator --no-dashboard
+```
+
+## CLI Commands
+
+```bash
+pinionos-emulator start
+pinionos-emulator mcp
+pinionos-emulator init
+```
+
+Useful options:
+- `--port <n>`
+- `--x402`
+- `--network base|base-sepolia`
+- `--no-dashboard`
+- `--config <path>`
+
+## Product Testing Workflow
+
+1. Start emulator locally.
+2. Configure your app's Pinion client with `apiUrl: 'http://localhost:4020'`.
+3. Run your app and test suite.
+4. Assert your product behavior (not just raw route responses).
+
+CI example:
+
+```bash
+npx pinionos-emulator --no-dashboard > /tmp/pinionos-emulator.log 2>&1 & EMU_PID=$!
+sleep 2
+npm test
+kill $EMU_PID
+```
+
+## Route Summary
+
+Core routes:
+- `GET /price/:token`
+- `GET /balance/:address`
+- `GET /wallet`
+- `GET /wallet/generate`
+- `GET /tx/:hash`
+- `POST /send`
+- `POST /trade`
+- `GET /fund/:address`
+- `POST /chat`
+- `POST /broadcast`
+- `GET /unlimited`
+- `POST /unlimited`
+- `GET /unlimited/verify?key=...`
+- `GET /unlimited/verify/:key`
+
+System routes:
+- `GET /`
+- `GET /health`
+- `POST /reset`
+- `POST /recording/start`
+- `POST /recording/stop`
+- `GET /recording/status`
+- `POST /facilitator/verify`
+- `GET /facilitator/status`
+- `ALL /x402/*`
+
+## Notes On Behavior
+
+- Responses are mock/simulated with realistic structure.
+- Success envelope includes `mock: true` and payment metadata.
+- Price path uses config override -> CoinGecko -> Binance -> fallback.
+- This is for development/testing, not production settlement.
+
+## Documentation
+
+- Detailed usage and testing guide: [user_guide.md](user_guide.md)
+- Planning/spec docs: [`docs/`](docs)
+
+## License
+
+MIT

package/dist/examples/basic-agent.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+process.env.PINION_API_URL = 'http://localhost:4020';
+const pinion_os_1 = require("pinion-os");
+async function run() {
+    const pinion = new pinion_os_1.PinionClient({
+        privateKey: '0x0000000000000000000000000000000000000000000000000000000000000001'
+    });
+    console.log('=== STEP 1: PRICE ===');
+    const price = await pinion.skills.price('ETH');
+    console.log(price);
+    console.log('\n=== STEP 2: BALANCE ===');
+    const balance = await pinion.skills.balance('0x123');
+    console.log(balance);
+    console.log('\n=== STEP 3: WALLET ===');
+    const wallet = await pinion.skills.wallet();
+    console.log(wallet);
+}
+run().catch((error) => {
+    console.error(error);
+    process.exit(1);
+});

package/dist/examples/custom-skill.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const server_1 = require("pinion-os/server");
+const server = (0, server_1.createSkillServer)({
+    payTo: '0x000000000000000000000000000000000000dEaD',
+    network: 'base'
+});
+server.add({
+    name: 'yieldRecs',
+    price: 0.01,
+    endpoint: '/yield-recs',
+    handler: async (req, res) => {
+        res.json({
+            data: {
+                recommendation: 'Rotate 20% into stablecoins during high volatility.',
+                confidence: 'medium'
+            },
+            mock: true
+        });
+    }
+});
+server.listen(4500, () => {
+    console.log('Custom skill server listening on :4500');
+});

package/dist/examples/yield-optimizer.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+process.env.PINION_API_URL = 'http://localhost:4020';
+const pinion_os_1 = require("pinion-os");
+const client = new pinion_os_1.PinionClient({
+    privateKey: '0x0000000000000000000000000000000000000000000000000000000000000001'
+});
+let iteration = 0;
+async function runOnce() {
+    iteration += 1;
+    console.log('\n=== Yield Check', iteration, '===');
+    const priceResult = await client.skills.price('ETH');
+    const ethPrice = Number(priceResult.data?.usd ?? 0);
+    console.log('ETH Price:', ethPrice);
+    const decision = ethPrice < 3000 ? 'BUY ETH->USDC rebalance' : 'HOLD';
+    console.log('Decision:', decision);
+    if (decision.startsWith('BUY')) {
+        const tradeResult = await client.skills.trade('ETH', 'USDC', '0.01');
+        console.log('Trade Executed:', tradeResult.data?.toAmount ?? 'n/a', 'USDC');
+        console.log('Simulated Yield: +$0.02');
+    }
+}
+runOnce().catch((error) => {
+    console.error(error);
+    process.exit(1);
+});
+setInterval(() => {
+    runOnce().catch((error) => {
+        console.error('Loop error:', error);
+    });
+}, 10000);

package/dist/src/app.js

@@ -0,0 +1,116 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApp = createApp;
+const cors_1 = __importDefault(require("cors"));
+const express_1 = __importDefault(require("express"));
+const config_1 = require("./config");
+const chaos_1 = require("./middleware/chaos");
+const paymentLogger_1 = require("./middleware/paymentLogger");
+const recorder_1 = require("./middleware/recorder");
+const x402_1 = require("./middleware/x402");
+const price_1 = require("./routes/price");
+const wallet_1 = require("./routes/wallet");
+const balance_1 = __importDefault(require("./routes/balance"));
+const broadcast_1 = __importDefault(require("./routes/broadcast"));
+const chat_1 = __importDefault(require("./routes/chat"));
+const fund_1 = require("./routes/fund");
+const send_1 = require("./routes/send");
+const trade_1 = require("./routes/trade");
+const facilitator_1 = require("./routes/facilitator");
+const tx_1 = __importDefault(require("./routes/tx"));
+const unlimited_1 = __importDefault(require("./routes/unlimited"));
+const x402service_1 = require("./routes/x402service");
+const balances_1 = require("./state/balances");
+const apiKeyStore_1 = require("./middleware/apiKeyStore");
+const types_1 = require("./types");
+function createApp(opts = {}) {
+    const dashboard = opts.dashboard;
+    const noop = {
+        logSkillCall() { },
+        updatePrices() { },
+        logError() { },
+        setWalletInfo() { },
+        destroy() { },
+    };
+    const db = dashboard ?? noop;
+    const app = (0, express_1.default)();
+    const config = (0, config_1.loadConfig)();
+    (0, balances_1.initBalances)();
+    app.use((0, cors_1.default)());
+    app.use(express_1.default.json());
+    // Request recording
+    app.use((0, recorder_1.recorderMiddleware)());
+    if (config.recording) {
+        (0, recorder_1.startRecording)();
+    }
+    // Chaos error injection
+    app.use((0, chaos_1.chaosMiddleware)(db));
+    // Log X-API-KEY usage
+    app.use((req, _res, next) => {
+        const apiKey = req.headers['x-api-key'];
+        if (typeof apiKey === 'string' && apiKey.length > 0) {
+            const entry = apiKeyStore_1.issuedKeys.get(apiKey);
+            const label = entry ? `✓ key valid (${apiKey.slice(0, 12)}...)` : `✗ key unknown (${apiKey.slice(0, 12)}...)`;
+            db.logSkillCall('x-api-key', '', label);
+        }
+        next();
+    });
+    app.use((0, paymentLogger_1.paymentLogger)(db));
+    app.use((0, x402_1.x402Middleware)(db));
+    app.get('/', (_req, res) => {
+        res.json({ status: 'ok', emulator: true });
+    });
+    app.get('/health', (_req, res) => {
+        res.json({ status: 'ok', emulator: true, port: config.port });
+    });
+    app.use('/price', (0, price_1.createPriceRouter)(db));
+    app.use('/wallet', (0, wallet_1.createWalletRouter)(db));
+    app.use('/balance', balance_1.default);
+    app.use('/tx', tx_1.default);
+    app.use('/send', (0, send_1.createSendRouter)(db));
+    app.use('/trade', (0, trade_1.createTradeRouter)(db));
+    app.use('/fund', (0, fund_1.createFundRouter)(db));
+    app.use('/chat', chat_1.default);
+    app.use('/unlimited', unlimited_1.default);
+    app.use('/broadcast', broadcast_1.default);
+    app.use('/facilitator', (0, facilitator_1.createFacilitatorRouter)(db));
+    app.use('/x402', (0, x402service_1.createX402ServiceRouter)(db));
+    app.post('/reset', (_req, res) => {
+        (0, balances_1.resetBalances)();
+        apiKeyStore_1.issuedKeys.clear();
+        db.logSkillCall('SYSTEM', '', 'State reset to config defaults');
+        res.json((0, types_1.success)({ message: 'All balances and API keys reset to defaults' }));
+    });
+    app.post('/recording/start', (_req, res) => {
+        (0, recorder_1.startRecording)();
+        db.logSkillCall('SYSTEM', '', 'Request recording started');
+        res.json((0, types_1.success)({ recording: true }));
+    });
+    app.post('/recording/stop', (_req, res) => {
+        (0, recorder_1.stopRecording)();
+        db.logSkillCall('SYSTEM', '', 'Request recording stopped');
+        res.json((0, types_1.success)({ recording: false }));
+    });
+    app.get('/recording/status', (_req, res) => {
+        res.json((0, types_1.success)({ recording: (0, recorder_1.isRecording)() }));
+    });
+    app.use((err, _req, res, next) => {
+        if (res.headersSent) {
+            next(err);
+            return;
+        }
+        if (err instanceof SyntaxError) {
+            res.status(400).json((0, types_1.errorResponse)('invalid json body'));
+            return;
+        }
+        db.logError(`internal emulator error: ${String(err?.message ?? err)}`);
+        res.status(500).json((0, types_1.errorResponse)('internal emulator error'));
+    });
+    app.use((_req, res) => {
+        res.status(404).json((0, types_1.errorResponse)('route not found'));
+    });
+    return { app, config };
+}

package/dist/src/cli.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_util_1 = require("node:util");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const HELP = `
+pinionos-emulator — Local PinionOS emulator for agent development
+
+Usage:
+  pinionos-emulator [command] [options]
+
+Commands:
+  start         Start the emulator (default)
+  mcp           Start MCP stdio server (emulator must be running)
+  init          Generate a starter config.json in the current directory
+
+Options:
+  --port <n>        Port to listen on (default: 4020)
+  --x402            Enable x402 payment simulation mode
+  --network <name>  Network: "base" (default) or "base-sepolia"
+  --no-dashboard    Run without the terminal dashboard UI
+  --config <path>   Path to config.json (default: ./config.json)
+  --help, -h        Show this help message
+  --version, -v     Show version
+
+Examples:
+  pinionos-emulator                       # Start with defaults
+  pinionos-emulator --port 3000 --x402    # Custom port + x402 mode
+  pinionos-emulator init                  # Create config.json
+  npx pinionos-emulator                   # Zero-install usage
+`.trim();
+async function main() {
+    const { values, positionals } = (0, node_util_1.parseArgs)({
+        args: process.argv.slice(2),
+        options: {
+            port: { type: 'string', short: 'p' },
+            x402: { type: 'boolean', default: false },
+            network: { type: 'string', short: 'n' },
+            'no-dashboard': { type: 'boolean', default: false },
+            config: { type: 'string', short: 'c' },
+            help: { type: 'boolean', short: 'h', default: false },
+            version: { type: 'boolean', short: 'v', default: false },
+        },
+        allowPositionals: true,
+        strict: true,
+    });
+    if (values.help) {
+        console.log(HELP);
+        return;
+    }
+    if (values.version) {
+        const pkg = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(__dirname, '..', 'package.json'), 'utf-8'));
+        console.log(pkg.version);
+        return;
+    }
+    // Apply config path override before command handling
+    if (values.config) {
+        const { setConfigPath } = await Promise.resolve().then(() => __importStar(require('./config')));
+        setConfigPath(values.config);
+        process.env.PINION_CONFIG_PATH = node_path_1.default.resolve(values.config);
+    }
+    const command = positionals[0] ?? 'start';
+    if (command === 'init') {
+        const { getDefaultConfig } = await Promise.resolve().then(() => __importStar(require('./config')));
+        const dest = node_path_1.default.resolve(process.cwd(), 'config.json');
+        if (node_fs_1.default.existsSync(dest)) {
+            console.error(`config.json already exists at ${dest}`);
+            process.exit(1);
+        }
+        node_fs_1.default.writeFileSync(dest, JSON.stringify(getDefaultConfig(), null, 2) + '\n');
+        console.log(`Created config.json at ${dest}`);
+        return;
+    }
+    if (command === 'mcp') {
+        await Promise.resolve().then(() => __importStar(require('./mcp/server')));
+        return;
+    }
+    // Apply CLI overrides
+    const overrides = {};
+    if (values.port)
+        overrides.port = parseInt(values.port, 10);
+    if (values.x402)
+        overrides.x402Mode = true;
+    if (values.network)
+        overrides.network = values.network;
+    if (Object.keys(overrides).length > 0) {
+        const { setCliOverrides } = await Promise.resolve().then(() => __importStar(require('./config')));
+        setCliOverrides(overrides);
+    }
+    // Set env flag for no-dashboard mode
+    if (values['no-dashboard']) {
+        process.env.PINION_NO_DASHBOARD = '1';
+    }
+    await Promise.resolve().then(() => __importStar(require('./emulator')));
+}
+main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+});

package/dist/src/client/MockPinionClient.js

@@ -0,0 +1,69 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MockPinionClient = void 0;
+exports.wrapAsSkillResponse = wrapAsSkillResponse;
+const axios_1 = __importDefault(require("axios"));
+function wrapAsSkillResponse(data) {
+    return {
+        status: 200,
+        data,
+        paidAmount: '0.01',
+        responseTimeMs: 0
+    };
+}
+/**
+ * Drop-in replacement for PinionClient when the SDK cannot be redirected via apiUrl.
+ * All skill methods return the same SkillResponse<T> shape as the real SDK.
+ * Usage:
+ *   const client = new MockPinionClient({ baseUrl: 'http://localhost:4020' });
+ *   const result = await client.skills.price('ETH');
+ *   console.log(result.data.priceUSD);
+ */
+class MockPinionClient {
+    constructor(options = {}) {
+        this.skills = {
+            price: (token) => this.get(`/price/${token}`),
+            balance: (address) => this.get(`/balance/${address}`),
+            wallet: () => this.get('/wallet/generate'),
+            tx: (hash) => this.get(`/tx/${hash}`),
+            fund: (address) => this.get(`/fund/${address ?? this.address}`),
+            chat: (message, history) => {
+                const messages = history
+                    ? [...history, { role: 'user', content: message }]
+                    : [{ role: 'user', content: message }];
+                return this.post('/chat', { messages });
+            },
+            send: (to, amount, token) => this.post('/send', { to, amount, token }),
+            trade: (src, dst, amount, slippage) => this.post('/trade', { src, dst, amount, slippage: slippage ?? 1 }),
+            broadcast: (tx, privateKey) => this.post('/broadcast', { tx, privateKey }),
+            unlimited: () => this.post('/unlimited', {}),
+            unlimitedVerify: async (key) => {
+                const res = await this.http.get('/unlimited/verify', { params: { key } });
+                return res.data;
+            }
+        };
+        this.http = axios_1.default.create({
+            baseURL: options.baseUrl ?? 'http://localhost:4020',
+            timeout: 10000
+        });
+        this.address = options.address ?? '';
+    }
+    async get(path) {
+        const start = Date.now();
+        const res = await this.http.get(path);
+        const body = res.data;
+        const data = body.data ?? body;
+        return { status: res.status, data, paidAmount: '0.01', responseTimeMs: Date.now() - start };
+    }
+    async post(path, payload) {
+        const start = Date.now();
+        const res = await this.http.post(path, payload);
+        const body = res.data;
+        const data = body.data ?? body;
+        return { status: res.status, data, paidAmount: '0.01', responseTimeMs: Date.now() - start };
+    }
+}
+exports.MockPinionClient = MockPinionClient;