apinow-sdk 0.15.0 → 0.16.0

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,128 @@ 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);
+// semantic search
+const results = await apinow.search('weather forecast', 5);
+
+// free endpoint info (cost, schema, wallet)
+const info = await apinow.info('gg402', 'horoscope');
 ```
 
-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.
+### `createClient(config)`
 
-## How It Works
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `privateKey` | `` `0x${string}` `` | — | EVM private key (required) |
+| `baseUrl` | `string` | `https://apinow.fun` | API base URL |
 
-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
+Returns:
 
-## API
+| 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) |
+| `listWorkflows(opts?)` | List workflows (free) |
+| `getWorkflow(id)` | Get workflow details (free) |
+| `runWorkflow(id, input)` | Run a workflow with automatic x402 payment |
+| `wallet` | Your wallet address |
+| `fetch` | Raw x402-wrapped `fetch` for advanced use |
 
-### `createClient(config)`
+### Workflows
 
-Creates an SDK client instance.
+Workflows chain multiple x402 endpoints into a single paid DAG pipeline with automatic payment splitting.
 
 ```typescript
-import { createClient } from 'apinow-sdk';
-// or
-import createClient from 'apinow-sdk';
+// list workflows
+const { workflows } = await apinow.listWorkflows({ status: 'active', limit: 10 });
 
-const apinow = createClient({
-  privateKey: '0x...',   // required — EVM private key
-  baseUrl: 'https://apinow.fun', // optional — defaults to https://apinow.fun
+// get workflow details (nodes, splits, pricing)
+const workflow = await apinow.getWorkflow('90931d9c8fb94df9');
+console.log(workflow.name, workflow.totalPrice, workflow.graph.nodes);
+
+// run a workflow — x402 payment covers all nodes + creator split
+const result = await apinow.runWorkflow('90931d9c8fb94df9', {
+  query: 'birthday gift ideas for a friend who loves cooking',
 });
 ```
 
-Returns an object with:
-
-| 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 |
-
----
+## CLI
 
-### `apinow.call(endpoint, opts?)`
-
-Call any APINow endpoint. Handles x402 payment automatically.
-
-```typescript
-const data = await apinow.call('/api/endpoints/apinowfun/translate-TRANSLATE', {
-  method: 'POST',
-  body: { text: 'Hello world', selectedLanguage: 'es' },
-});
+```bash
+npx apinow <command>
 ```
 
-**Parameters:**
+### `search` — find endpoints
 
-| 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 |
+```bash
+npx apinow search "weather api" --limit 5
+```
 
-**Returns:** `Promise<any>` — parsed JSON response.
+### `list` — browse endpoints
 
----
+```bash
+npx apinow list                          # popular endpoints
+npx apinow list --sort newest --limit 10
+npx apinow list --namespace gg402
+npx apinow list --search translate
+```
 
-### `apinow.search(query, limit?)`
+### `info` — endpoint details
 
-Semantic search across all APINow endpoints.
+Shows cost, wallet, chain, input/output schemas, and examples.
 
-```typescript
-const results = await apinow.search('translate text', 5);
+```bash
+npx apinow info gg402/horoscope
 ```
 
-| Param | Type | Default | Description |
-|-------|------|---------|-------------|
-| `query` | `string` | — | Search query |
-| `limit` | `number` | `10` | Max results |
+### `call` — call an endpoint (paid)
 
----
+```bash
+APINOW_WALLET_PKEY=0x... npx apinow call gg402/horoscope -d '{"sign":"aries"}'
+npx apinow call ns/endpoint -m GET -k 0xYOUR_KEY
+```
 
-### `apinow.info(namespace, endpointName)`
+| 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`) |
 
-Get public endpoint details. Free — no payment required.
+### `workflows` — list workflows
 
-```typescript
-const details = await apinow.info('apinowfun', 'translate-TRANSLATE');
+```bash
+npx apinow workflows
+npx apinow workflows --status active --limit 10
+npx apinow workflows --creator 0x32e8...E934
 ```
 
----
-
-### `apinow.fetch`
+### `workflow` — workflow details
 
-The raw x402-wrapped `fetch` function, if you need full control over requests.
-
-```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 workflow 90931d9c8fb94df9
 ```
 
-## Types
+### `run-workflow` — run a workflow (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 run-workflow 90931d9c8fb94df9 -d '{"query":"birthday gift ideas"}'
 ```
 
+| Flag | Description |
+|------|-------------|
+| `-d, --data <json>` | JSON input (default: `{"query":"hello world"}`) |
+| `-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.js

@@ -6,7 +6,7 @@ const program = new Command();
 program
     .name('apinow')
     .description('CLI for APINow.fun — search, inspect, and call pay-per-request APIs')
-    .version('0.15.0');
+    .version('0.16.0');
 // ─── Helpers ───
 function getPrivateKey(opts) {
     const raw = opts.key || process.env.APINOW_WALLET_PKEY || process.env.PRIVATE_KEY;
@@ -216,4 +216,100 @@ program
         process.exit(1);
     }
 });
+// ─── workflows ───
+program
+    .command('workflows')
+    .description('List workflows')
+    .option('-l, --limit <n>', 'Max results', '20')
+    .option('-c, --creator <address>', 'Filter by creator wallet')
+    .option('-s, --status <status>', 'Filter by status: active | draft | all', 'all')
+    .action(async (opts) => {
+    try {
+        const params = new URLSearchParams({ limit: opts.limit, status: opts.status });
+        if (opts.creator)
+            params.set('creator', opts.creator);
+        const data = await fetchJson(`${API_BASE}/api/workflows?${params}`);
+        const workflows = data.workflows || [];
+        if (!workflows.length) {
+            console.log('No workflows found.');
+            return;
+        }
+        const rows = [['ID', 'NAME', 'STATUS', 'NODES', 'COST', 'DESCRIPTION']];
+        for (const w of workflows) {
+            rows.push([
+                w.workflowId,
+                truncate(w.name || '', 24),
+                w.status,
+                String(w.graph?.nodes?.length || 0),
+                `$${w.totalPrice}`,
+                truncate(w.description || '', 40),
+            ]);
+        }
+        printTable(rows);
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+// ─── workflow info ───
+program
+    .command('workflow <id>')
+    .description('Get workflow details')
+    .action(async (id) => {
+    try {
+        const data = await fetchJson(`${API_BASE}/api/workflows/${id}`);
+        console.log(`\n  ${data.name}`);
+        console.log(`  ${'─'.repeat(40)}`);
+        console.log(`  ${data.description || '(no description)'}\n`);
+        console.log(`  ID:      ${data.workflowId}`);
+        console.log(`  Status:  ${data.status}`);
+        console.log(`  Cost:    $${data.totalPrice} USDC`);
+        console.log(`  Chain:   ${data.chain || 'base'}`);
+        console.log(`  Creator: ${data.creatorWallet}`);
+        console.log(`  Nodes:   ${data.graph?.nodes?.length || 0}`);
+        if (data.graph?.nodes?.length) {
+            console.log(`\n  Pipeline:`);
+            for (const node of data.graph.nodes) {
+                const deps = node.dependsOn?.length ? ` (depends on: ${node.dependsOn.join(', ')})` : '';
+                const isOutput = node.id === data.graph.outputNode ? ' [output]' : '';
+                console.log(`    → ${node.id}: ${node.endpoint}${deps}${isOutput}`);
+            }
+        }
+        if (data.splits?.length) {
+            console.log(`\n  Payment Split:`);
+            for (const s of data.splits) {
+                const pct = (s.basisPoints / 100).toFixed(1);
+                const usd = (parseFloat(data.totalPrice) * s.basisPoints / 10000).toFixed(4);
+                console.log(`    ${s.label}: ${pct}% ($${usd})`);
+            }
+        }
+        console.log('');
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+// ─── run workflow ───
+program
+    .command('run-workflow <id>')
+    .description('Run a workflow (x402 paid)')
+    .option('-d, --data <json>', 'JSON input', '{"query":"hello world"}')
+    .option('-k, --key <privateKey>', 'Wallet private key')
+    .action(async (id, opts) => {
+    try {
+        const privateKey = getPrivateKey(opts);
+        const body = JSON.parse(opts.data);
+        const details = await fetchJson(`${API_BASE}/api/workflows/${id}`);
+        console.error(`Running workflow "${details.name}" — cost: $${details.totalPrice} USDC`);
+        const apinow = createClient({ privateKey });
+        const result = await apinow.runWorkflow(id, body);
+        console.log(JSON.stringify(result, null, 2));
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
 program.parse();

package/dist/index.d.ts

@@ -27,6 +27,25 @@ export declare function createClient(config: ApinowConfig): {
      * Get public endpoint info (free, no payment).
      */
     info(namespace: string, endpointName: string): Promise<any>;
+    /**
+     * List workflows. Optionally filter by creator or status.
+     */
+    listWorkflows(opts?: {
+        creator?: string;
+        status?: string;
+        limit?: number;
+    }): Promise<any>;
+    /**
+     * Get workflow details by ID.
+     */
+    getWorkflow(workflowId: string): Promise<any>;
+    /**
+     * Run a workflow. Handles x402 payment automatically.
+     *
+     * @example
+     * const result = await apinow.runWorkflow('90931d9c8fb94df9', { query: 'hello world' });
+     */
+    runWorkflow(workflowId: string, input: Record<string, any>): Promise<any>;
     /**
      * The underlying x402-wrapped fetch, for advanced use.
      */

package/dist/index.js

@@ -58,6 +58,44 @@ export function createClient(config) {
                 throw new Error(`Failed to fetch info: ${res.status}`);
             return res.json();
         },
+        // ─── Workflows ───
+        /**
+         * List workflows. Optionally filter by creator or status.
+         */
+        async listWorkflows(opts = {}) {
+            const params = new URLSearchParams();
+            if (opts.limit)
+                params.set('limit', String(opts.limit));
+            if (opts.creator)
+                params.set('creator', opts.creator);
+            if (opts.status)
+                params.set('status', opts.status);
+            const res = await fetch(`${baseUrl}/api/workflows?${params}`);
+            if (!res.ok)
+                throw new Error(`Failed to list workflows: ${res.status}`);
+            return res.json();
+        },
+        /**
+         * Get workflow details by ID.
+         */
+        async getWorkflow(workflowId) {
+            const res = await fetch(`${baseUrl}/api/workflows/${workflowId}`);
+            if (!res.ok)
+                throw new Error(`Failed to get workflow: ${res.status}`);
+            return res.json();
+        },
+        /**
+         * Run a workflow. Handles x402 payment automatically.
+         *
+         * @example
+         * const result = await apinow.runWorkflow('90931d9c8fb94df9', { query: 'hello world' });
+         */
+        async runWorkflow(workflowId, input) {
+            return this.call(`/api/workflows/${workflowId}/run`, {
+                method: 'POST',
+                body: input,
+            });
+        },
         /**
          * The underlying x402-wrapped fetch, for advanced use.
          */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "apinow-sdk",
-  "version": "0.15.0",
-  "description": "Pay-per-call API SDK & CLI for APINow.fun — wraps x402 so you don't have to",
+  "version": "0.16.0",
+  "description": "Pay-per-call API SDK & CLI for APINow.fun — endpoints + workflows, wraps x402 so you don't have to",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -24,7 +24,9 @@
     "web3",
     "ai",
     "llm",
-    "cli"
+    "cli",
+    "workflow",
+    "dag"
   ],
   "author": "ApiNow.fun",
   "license": "MIT",