apinow-sdk 0.14.0 → 0.15.1

package/README.md

@@ -1,14 +1,12 @@
 # apinow-sdk
 
-Pay-per-call API SDK for [APINow.fun](https://apinow.fun) — wraps [x402](https://www.x402.org/) so you don't have to.
-
-## Install
+Pay-per-call API SDK & CLI for [APINow.fun](https://apinow.fun) — wraps [x402](https://www.x402.org/) so you don't have to.
 
 ```bash
 npm install apinow-sdk
 ```
 
-## Quick Start
+## SDK
 
 ```typescript
 import { createClient } from 'apinow-sdk';
@@ -17,133 +15,82 @@ const apinow = createClient({
   privateKey: process.env.PRIVATE_KEY as `0x${string}`,
 });
 
-const result = await apinow.call('/api/endpoints/apinowfun/translate-TRANSLATE', {
+// call any endpoint — x402 payment is handled automatically
+const data = await apinow.call('/api/endpoints/apinowfun/translate', {
   method: 'POST',
-  body: { text: 'Hello world', selectedLanguage: 'es' },
+  body: { text: 'Hello world', targetLanguage: 'es' },
 });
 
-console.log(result);
-```
-
-That's it. If the endpoint requires payment, the SDK handles the full [x402 payment flow](https://www.x402.org/) automatically — no manual token handling, no extra steps.
-
-## How It Works
-
-1. You call an APINow endpoint via `apinow.call()`
-2. If the server responds with `402 Payment Required`, the underlying `@x402/fetch` layer intercepts it
-3. Payment is signed and submitted using your wallet
-4. The original request is retried with proof of payment
-5. You get the API response back
-
-## API
-
-### `createClient(config)`
-
-Creates an SDK client instance.
-
-```typescript
-import { createClient } from 'apinow-sdk';
-// or
-import createClient from 'apinow-sdk';
+// semantic search
+const results = await apinow.search('weather forecast', 5);
 
-const apinow = createClient({
-  privateKey: '0x...',   // required — EVM private key
-  baseUrl: 'https://apinow.fun', // optional — defaults to https://apinow.fun
-});
+// free endpoint info (cost, schema, wallet)
+const info = await apinow.info('gg402', 'horoscope');
 ```
 
-Returns an object with:
+### `createClient(config)`
 
-| Property | Description |
-|----------|-------------|
-| `wallet` | Your wallet address (derived from private key) |
-| `call()` | Call any APINow endpoint with automatic x402 payment |
-| `search()` | Semantic search across all APINow endpoints |
-| `info()` | Get public endpoint info (free, no payment) |
-| `fetch` | The underlying x402-wrapped `fetch` for advanced use |
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `privateKey` | `` `0x${string}` `` | — | EVM private key (required) |
+| `baseUrl` | `string` | `https://apinow.fun` | API base URL |
 
----
+Returns:
 
-### `apinow.call(endpoint, opts?)`
+| Method | Description |
+|--------|-------------|
+| `call(endpoint, opts?)` | Call any endpoint with automatic x402 payment |
+| `search(query, limit?)` | Semantic search across all endpoints |
+| `info(ns, name)` | Get endpoint details (free) |
+| `wallet` | Your wallet address |
+| `fetch` | Raw x402-wrapped `fetch` for advanced use |
 
-Call any APINow endpoint. Handles x402 payment automatically.
+## CLI
 
-```typescript
-const data = await apinow.call('/api/endpoints/apinowfun/translate-TRANSLATE', {
-  method: 'POST',
-  body: { text: 'Hello world', selectedLanguage: 'es' },
-});
+```bash
+npx apinow <command>
 ```
 
-**Parameters:**
-
-| Param | Type | Default | Description |
-|-------|------|---------|-------------|
-| `endpoint` | `string` | — | Full URL or path (paths are resolved against `baseUrl`) |
-| `opts.method` | `'GET' \| 'POST' \| 'PUT' \| 'DELETE'` | `'POST'` | HTTP method |
-| `opts.body` | `Record<string, any>` | — | Request body (ignored for GET) |
-| `opts.headers` | `Record<string, string>` | — | Additional headers |
+### `search` — find endpoints
 
-**Returns:** `Promise<any>` — parsed JSON response.
-
----
-
-### `apinow.search(query, limit?)`
-
-Semantic search across all APINow endpoints.
-
-```typescript
-const results = await apinow.search('translate text', 5);
+```bash
+npx apinow search "weather api" --limit 5
 ```
 
-| Param | Type | Default | Description |
-|-------|------|---------|-------------|
-| `query` | `string` | — | Search query |
-| `limit` | `number` | `10` | Max results |
-
----
-
-### `apinow.info(namespace, endpointName)`
+### `list` — browse endpoints
 
-Get public endpoint details. Free — no payment required.
-
-```typescript
-const details = await apinow.info('apinowfun', 'translate-TRANSLATE');
+```bash
+npx apinow list                          # popular endpoints
+npx apinow list --sort newest --limit 10
+npx apinow list --namespace gg402
+npx apinow list --search translate
 ```
 
----
-
-### `apinow.fetch`
+### `info` — endpoint details
 
-The raw x402-wrapped `fetch` function, if you need full control over requests.
+Shows cost, wallet, chain, input/output schemas, and examples.
 
-```typescript
-const res = await apinow.fetch('https://apinow.fun/api/endpoints/...', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({ key: 'value' }),
-});
+```bash
+npx apinow info gg402/horoscope
 ```
 
-## Types
+### `call` — call an endpoint (paid)
 
-```typescript
-interface ApinowConfig {
-  privateKey: `0x${string}`;
-  baseUrl?: string;
-}
-
-interface CallOptions {
-  method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
-  body?: Record<string, any>;
-  headers?: Record<string, string>;
-}
+```bash
+APINOW_WALLET_PKEY=0x... npx apinow call gg402/horoscope -d '{"sign":"aries"}'
+npx apinow call ns/endpoint -m GET -k 0xYOUR_KEY
 ```
 
+| Flag | Description |
+|------|-------------|
+| `-d, --data <json>` | JSON request body |
+| `-m, --method <method>` | HTTP method (default: from endpoint) |
+| `-k, --key <privateKey>` | Wallet key (or set `APINOW_WALLET_PKEY`) |
+
 ## Requirements
 
-- Node.js v18+ (uses native `fetch`)
-- An EVM wallet with funds on Base for paid endpoints
+- Node.js v18+
+- EVM wallet with funds on Base for paid endpoints
 
 ## License
 

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { createClient } from './index.js';
+const API_BASE = 'https://apinow.fun';
+const program = new Command();
+program
+    .name('apinow')
+    .description('CLI for APINow.fun — search, inspect, and call pay-per-request APIs')
+    .version('0.15.0');
+// ─── Helpers ───
+function getPrivateKey(opts) {
+    const raw = opts.key || process.env.APINOW_WALLET_PKEY || process.env.PRIVATE_KEY;
+    if (!raw) {
+        console.error('Error: Private key required. Set APINOW_WALLET_PKEY or pass --key');
+        process.exit(1);
+    }
+    return (raw.startsWith('0x') ? raw : `0x${raw}`);
+}
+async function fetchJson(url, init) {
+    const res = await fetch(url, init);
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`${res.status} ${res.statusText}: ${body}`);
+    }
+    return res.json();
+}
+function formatUsd(paymentOptions) {
+    if (!paymentOptions?.length)
+        return 'free';
+    const p = paymentOptions[0];
+    const usd = p.usdAmount ?? p.amount ?? 0;
+    return `$${Number(usd).toFixed(4)}`;
+}
+function printTable(rows) {
+    if (!rows.length)
+        return;
+    const widths = rows[0].map((_, col) => Math.max(...rows.map((r) => (r[col] || '').length)));
+    for (const row of rows) {
+        console.log(row.map((cell, i) => (cell || '').padEnd(widths[i])).join('  '));
+    }
+}
+function truncate(s, max) {
+    return s.length > max ? s.slice(0, max - 1) + '…' : s;
+}
+// ─── search ───
+program
+    .command('search <query>')
+    .description('Semantic search across all endpoints')
+    .option('-l, --limit <n>', 'Max results', '10')
+    .action(async (query, opts) => {
+    try {
+        const data = await fetchJson(`${API_BASE}/api/endpoints/semantic-search`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ query, limit: Number(opts.limit) }),
+        });
+        const endpoints = data.endpoints || data.results || data;
+        if (!Array.isArray(endpoints) || !endpoints.length) {
+            console.log('No results found.');
+            return;
+        }
+        const rows = [['ENDPOINT', 'METHOD', 'COST', 'DESCRIPTION']];
+        for (const ep of endpoints) {
+            const key = `${ep.namespace}/${ep.endpointName}`;
+            rows.push([
+                key,
+                ep.httpMethod || 'POST',
+                formatUsd(ep.paymentOptions),
+                truncate(ep.description || '', 60),
+            ]);
+        }
+        printTable(rows);
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+// ─── list ───
+program
+    .command('list')
+    .description('List available endpoints')
+    .option('-l, --limit <n>', 'Max results', '20')
+    .option('-s, --sort <sortBy>', 'Sort by: popular | newest', 'popular')
+    .option('-n, --namespace <ns>', 'Filter by namespace')
+    .option('-q, --search <term>', 'Text search filter')
+    .action(async (opts) => {
+    try {
+        const params = new URLSearchParams({
+            limit: opts.limit,
+            sortBy: opts.sort,
+        });
+        if (opts.namespace)
+            params.set('namespace', opts.namespace);
+        if (opts.search)
+            params.set('search', opts.search);
+        const data = await fetchJson(`${API_BASE}/api/endpoints?${params}`);
+        const endpoints = data.endpoints || [];
+        if (!endpoints.length) {
+            console.log('No endpoints found.');
+            return;
+        }
+        const rows = [['ENDPOINT', 'METHOD', 'COST', 'CALLS', 'DESCRIPTION']];
+        for (const ep of endpoints) {
+            rows.push([
+                `${ep.namespace}/${ep.endpointName}`,
+                ep.httpMethod || 'POST',
+                formatUsd(ep.paymentOptions),
+                String(ep.callCount || 0),
+                truncate(ep.description || '', 50),
+            ]);
+        }
+        printTable(rows);
+        if (data.hasMore) {
+            console.log(`\n… more results available (showing ${endpoints.length})`);
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+// ─── info ───
+program
+    .command('info <endpoint>')
+    .description('Get endpoint details (cost, wallet, schemas, examples)')
+    .action(async (endpoint) => {
+    try {
+        if (!endpoint.includes('/')) {
+            throw new Error('Format: namespace/endpoint-name');
+        }
+        const [ns, ep] = endpoint.split('/');
+        const data = await fetchJson(`${API_BASE}/api/endpoints/${ns}/${ep}/details`);
+        const cost = formatUsd(data.paymentOptions);
+        const payment = data.paymentOptions?.[0];
+        console.log(`\n  ${data.namespace}/${data.endpointName}`);
+        console.log(`  ${'─'.repeat(40)}`);
+        console.log(`  ${data.description || '(no description)'}\n`);
+        console.log(`  Method:  ${data.httpMethod || 'POST'}`);
+        console.log(`  Cost:    ${cost}`);
+        console.log(`  Chain:   ${data.chain || 'base'}`);
+        console.log(`  Wallet:  ${data.walletAddress || '—'}`);
+        if (data.model)
+            console.log(`  Model:   ${data.model}`);
+        if (data.tags?.length)
+            console.log(`  Tags:    ${data.tags.join(', ')}`);
+        if (data.docsUrl)
+            console.log(`  Docs:    ${data.docsUrl}`);
+        if (payment) {
+            console.log(`\n  Payment:`);
+            console.log(`    Network:  ${payment.network || 'base-sepolia'}`);
+            console.log(`    Token:    ${payment.resource || payment.token || 'USDC'}`);
+            console.log(`    Amount:   ${payment.amount ?? '—'}`);
+            if (payment.usdAmount != null)
+                console.log(`    USD:      $${payment.usdAmount}`);
+        }
+        if (data.querySchema) {
+            console.log(`\n  Input Schema:`);
+            const schema = data.querySchema;
+            if (schema.properties) {
+                const required = new Set(schema.required || []);
+                for (const [key, val] of Object.entries(schema.properties)) {
+                    const req = required.has(key) ? ' (required)' : '';
+                    const desc = val.description ? ` — ${val.description}` : '';
+                    const ex = val.example ? `  e.g. ${JSON.stringify(val.example)}` : '';
+                    console.log(`    ${key}: ${val.type || 'any'}${req}${desc}${ex}`);
+                }
+            }
+            else {
+                console.log(`    ${JSON.stringify(schema, null, 4).replace(/\n/g, '\n    ')}`);
+            }
+        }
+        if (data.responseSchema) {
+            console.log(`\n  Output Schema:`);
+            console.log(`    ${JSON.stringify(data.responseSchema, null, 4).replace(/\n/g, '\n    ')}`);
+        }
+        if (data.exampleQuery) {
+            console.log(`\n  Example Input:`);
+            console.log(`    ${JSON.stringify(data.exampleQuery, null, 2).replace(/\n/g, '\n    ')}`);
+        }
+        console.log('');
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+// ─── call ───
+program
+    .command('call <endpoint>')
+    .description('Call an endpoint (x402 paid)')
+    .option('-d, --data <json>', 'JSON body')
+    .option('-m, --method <method>', 'HTTP method')
+    .option('-k, --key <privateKey>', 'Wallet private key')
+    .action(async (endpoint, opts) => {
+    try {
+        if (!endpoint.includes('/')) {
+            throw new Error('Format: namespace/endpoint-name');
+        }
+        const privateKey = getPrivateKey(opts);
+        const [ns, ep] = endpoint.split('/');
+        const details = await fetchJson(`${API_BASE}/api/endpoints/${ns}/${ep}/details`);
+        const method = (opts.method || details?.httpMethod || 'POST').toUpperCase();
+        const body = opts.data ? JSON.parse(opts.data) : undefined;
+        const cost = formatUsd(details?.paymentOptions);
+        console.error(`Calling ${ns}/${ep} [${method}] — cost: ${cost}`);
+        const apinow = createClient({ privateKey });
+        const result = await apinow.call(`/api/endpoints/${ns}/${ep}`, {
+            method: method,
+            ...(body ? { body } : {}),
+        });
+        console.log(JSON.stringify(result, null, 2));
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+program.parse();

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "apinow-sdk",
-  "version": "0.14.0",
-  "description": "Pay-per-call API SDK for APINow.fun — wraps x402 so you don't have to",
+  "version": "0.15.1",
+  "description": "Pay-per-call API SDK & CLI for APINow.fun — wraps x402 so you don't have to",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
+  "bin": {
+    "apinow": "dist/cli.js"
+  },
   "files": [
     "dist"
   ],
@@ -20,7 +23,8 @@
     "base",
     "web3",
     "ai",
-    "llm"
+    "llm",
+    "cli"
   ],
   "author": "ApiNow.fun",
   "license": "MIT",
@@ -30,8 +34,9 @@
   },
   "homepage": "https://apinow.fun",
   "dependencies": {
-    "@x402/fetch": "^2.3.0",
     "@x402/evm": "^2.3.1",
+    "@x402/fetch": "^2.3.0",
+    "commander": "^13.1.0",
     "viem": "^2.38.3"
   },
   "devDependencies": {