apinow-sdk 0.22.0 → 0.23.0

package/README.md

@@ -56,6 +56,13 @@ Returns:
 | `listWorkflows(opts?)` | List workflows (free) |
 | `getWorkflow(id)` | Get workflow details (free) |
 | `runWorkflow(id, input)` | Run a workflow with automatic x402 payment |
+| `generateUI(opts)` | Start AI UI generation for an endpoint (async) |
+| `generateUIAndWait(opts)` | Generate UI and poll until complete |
+| `getGeneratedUI(id)` | Get a generated UI by ID |
+| `listGeneratedUIs(key, sort?)` | List generated UIs for an endpoint |
+| `checkFreeUI()` | Check free-tier generation eligibility |
+| `reactToUI(id, action, comment?)` | Like/dislike/comment on a generated UI |
+| `deleteGeneratedUI(id)` | Delete a generated UI |
 | `wallet` | Your wallet address |
 | `fetch` | Raw x402-wrapped `fetch` for advanced use |
 
@@ -77,6 +84,38 @@ const result = await apinow.runWorkflow('90931d9c8fb94df9', {
 });
 ```
 
+### AI UI Generation
+
+Generate interactive Arrow JS sandbox UIs for any endpoint — ideal for AI agents that need a visual interface.
+
+```typescript
+// generate a UI and wait for it to complete
+const ui = await apinow.generateUIAndWait({
+  endpointName: 'horoscope',
+  namespace: 'gg402',
+  description: 'Get daily horoscope for a zodiac sign',
+  querySchema: { properties: { sign: { type: 'string' } } },
+  responseSchema: { properties: { horoscope: { type: 'string' } } },
+  customPrompt: 'Use a starry night theme',
+});
+console.log(ui.status); // 'complete'
+console.log(ui.source); // { "main.ts": "...", "main.css": "..." }
+
+// or fire-and-forget + poll yourself
+const { id } = await apinow.generateUI({ endpointName: 'translate', namespace: 'apinowfun' });
+const doc = await apinow.getGeneratedUI(id); // poll until doc.status !== 'generating'
+
+// list existing UIs for an endpoint
+const { uis } = await apinow.listGeneratedUIs('gg402/horoscope', 'popular');
+
+// social
+await apinow.reactToUI(ui._id, 'like');
+await apinow.reactToUI(ui._id, 'comment', 'Great UI!');
+
+// check free-tier
+const { free, remaining } = await apinow.checkFreeUI();
+```
+
 ## CLI
 
 ```bash
@@ -144,6 +183,57 @@ APINOW_WALLET_PKEY=0x... npx apinow run-workflow 90931d9c8fb94df9 -d '{"query":"
 | `-d, --data <json>` | JSON input (default: `{"query":"hello world"}`) |
 | `-k, --key <privateKey>` | Wallet key (or set `APINOW_WALLET_PKEY`) |
 
+### `ui-generate` — generate an AI UI for an endpoint
+
+Generates an interactive Arrow JS sandbox UI. Automatically fetches the endpoint's schema and examples, sends the generation request, and polls until complete.
+
+```bash
+APINOW_WALLET_PKEY=0x... npx apinow ui-generate gg402/horoscope
+APINOW_WALLET_PKEY=0x... npx apinow ui-generate gg402/horoscope --prompt "dark theme with animations"
+npx apinow ui-generate ns/endpoint --no-wait -k 0xKEY  # returns immediately with ID
+```
+
+| Flag | Description |
+|------|-------------|
+| `-p, --prompt <text>` | Custom instructions for the UI |
+| `--no-wait` | Return immediately without polling |
+| `--timeout <ms>` | Polling timeout (default: 120000) |
+| `-k, --key <privateKey>` | Wallet key (or set `APINOW_WALLET_PKEY`) |
+
+### `ui-list` — list generated UIs
+
+```bash
+npx apinow ui-list gg402/horoscope
+npx apinow ui-list gg402/horoscope --sort recent
+```
+
+### `ui-get` — get a generated UI by ID
+
+```bash
+npx apinow ui-get 665a1b2c3d4e5f6a7b8c9d0e
+npx apinow ui-get 665a1b2c3d4e5f6a7b8c9d0e --source-only  # just the Arrow JS source
+```
+
+### `ui-like` / `ui-dislike` / `ui-comment` — social actions
+
+```bash
+APINOW_WALLET_PKEY=0x... npx apinow ui-like <id>
+APINOW_WALLET_PKEY=0x... npx apinow ui-dislike <id>
+APINOW_WALLET_PKEY=0x... npx apinow ui-comment <id> -m "Nice UI!"
+```
+
+### `ui-delete` — delete a generated UI
+
+```bash
+APINOW_WALLET_PKEY=0x... npx apinow ui-delete <id>
+```
+
+### `ui-free-check` — check free-tier eligibility
+
+```bash
+APINOW_WALLET_PKEY=0x... npx apinow ui-free-check
+```
+
 ### `discover` — check the x402 price of any URL (free)
 
 ```bash

package/dist/cli.js

@@ -7,7 +7,7 @@ const program = new Command();
 program
     .name('apinow')
     .description('CLI for APINow.fun — search, inspect, and call pay-per-request APIs')
-    .version('0.22.0');
+    .version('0.23.0');
 // ─── Helpers ───
 function getPrivateKey(opts) {
     const raw = opts.key || process.env.APINOW_WALLET_PKEY || process.env.PRIVATE_KEY;
@@ -560,6 +560,231 @@ program
         process.exit(1);
     }
 });
+// ─── ui-generate ───
+program
+    .command('ui-generate <endpoint>')
+    .description('Generate an AI UI for an endpoint (namespace/name). Polls until complete.')
+    .option('-p, --prompt <prompt>', 'Custom prompt / instructions for the UI')
+    .option('--no-wait', 'Return immediately without polling')
+    .option('--timeout <ms>', 'Polling timeout in ms', '120000')
+    .option('-k, --key <privateKey>', 'Wallet private key')
+    .action(async (endpoint, opts) => {
+    try {
+        if (!endpoint.includes('/'))
+            throw new Error('Format: namespace/endpoint-name');
+        const [ns, ep] = endpoint.split('/');
+        const { address } = getWallet(opts);
+        const details = await fetchJson(`${API_BASE}/api/endpoints/${ns}/${ep}/details`);
+        const body = {
+            endpointName: ep,
+            namespace: ns,
+            description: details.description || '',
+            querySchema: details.querySchema || {},
+            responseSchema: details.responseSchema || {},
+            walletAddress: address,
+        };
+        if (details.exampleQuery || details.exampleOutput) {
+            body.examples = [{ input: details.exampleQuery, output: details.exampleOutput }];
+        }
+        if (opts.prompt)
+            body.customPrompt = opts.prompt;
+        console.error(`Generating UI for ${ns}/${ep}…`);
+        const { id } = await fetchJson(`${API_BASE}/api/ai/generate-ui`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        if (!opts.wait) {
+            console.log(JSON.stringify({ id, status: 'generating' }, null, 2));
+            return;
+        }
+        const timeout = Number(opts.timeout);
+        const deadline = Date.now() + timeout;
+        process.stderr.write('  Polling');
+        while (Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, 3000));
+            process.stderr.write('.');
+            const doc = await fetchJson(`${API_BASE}/api/ai/generate-ui?id=${encodeURIComponent(id)}`);
+            if (doc.status === 'complete') {
+                console.error(' done!');
+                console.log(JSON.stringify({
+                    id: doc._id,
+                    status: doc.status,
+                    endpointKey: doc.endpointKey,
+                    model: doc.model,
+                    files: Object.keys(doc.source || {}),
+                    source: doc.source,
+                    viewUrl: `https://apinow.fun/try/${ns}/${ep}`,
+                }, null, 2));
+                return;
+            }
+            if (doc.status === 'error') {
+                console.error(' failed!');
+                console.error(`Error: ${doc.errorMessage}`);
+                process.exit(1);
+            }
+        }
+        console.error(` timed out after ${timeout / 1000}s`);
+        console.log(JSON.stringify({ id, status: 'generating', note: 'Still generating — poll with: apinow ui-get ' + id }));
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+// ─── ui-list ───
+program
+    .command('ui-list <endpoint>')
+    .description('List generated UIs for an endpoint (namespace/name)')
+    .option('-s, --sort <sort>', 'Sort: popular | recent', 'popular')
+    .action(async (endpoint, opts) => {
+    try {
+        if (!endpoint.includes('/'))
+            throw new Error('Format: namespace/endpoint-name');
+        const params = new URLSearchParams({ endpointKey: endpoint, sort: opts.sort });
+        const data = await fetchJson(`${API_BASE}/api/ai/generate-ui?${params}`);
+        const uis = data.uis || [];
+        if (!uis.length) {
+            console.log('No generated UIs found.');
+            return;
+        }
+        const rows = [['ID', 'STATUS', 'MODEL', 'OPENS', 'LIKES', 'PROMPT', 'CREATED']];
+        for (const ui of uis) {
+            rows.push([
+                ui._id,
+                ui.status,
+                ui.model || '—',
+                String(ui.openCount || 0),
+                String((ui.likes || []).length),
+                truncate(ui.customPrompt || '(default)', 30),
+                new Date(ui.createdAt).toLocaleDateString(),
+            ]);
+        }
+        printTable(rows);
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+// ─── ui-get ───
+program
+    .command('ui-get <id>')
+    .description('Get a generated UI by ID (includes source code)')
+    .option('--source-only', 'Print only the source JSON')
+    .action(async (id, opts) => {
+    try {
+        const doc = await fetchJson(`${API_BASE}/api/ai/generate-ui?id=${encodeURIComponent(id)}`);
+        if (opts.sourceOnly) {
+            console.log(JSON.stringify(doc.source, null, 2));
+            return;
+        }
+        console.log(JSON.stringify(doc, null, 2));
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+// ─── ui-delete ───
+program
+    .command('ui-delete <id>')
+    .description('Delete a generated UI (must be creator)')
+    .option('-k, --key <privateKey>', 'Wallet private key')
+    .action(async (id, opts) => {
+    try {
+        const { address } = getWallet(opts);
+        const data = await fetchJson(`${API_BASE}/api/ai/generate-ui`, {
+            method: 'DELETE',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ id, wallet: address }),
+        });
+        console.log(JSON.stringify(data, null, 2));
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+// ─── ui-like / ui-dislike ───
+program
+    .command('ui-like <id>')
+    .description('Like a generated UI')
+    .option('-k, --key <privateKey>', 'Wallet private key')
+    .action(async (id, opts) => {
+    try {
+        const { address } = getWallet(opts);
+        const data = await fetchJson(`${API_BASE}/api/ai/generate-ui`, {
+            method: 'PATCH',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ id, action: 'like', wallet: address }),
+        });
+        console.log(`Likes: ${data.likes}  Dislikes: ${data.dislikes}`);
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+program
+    .command('ui-dislike <id>')
+    .description('Dislike a generated UI')
+    .option('-k, --key <privateKey>', 'Wallet private key')
+    .action(async (id, opts) => {
+    try {
+        const { address } = getWallet(opts);
+        const data = await fetchJson(`${API_BASE}/api/ai/generate-ui`, {
+            method: 'PATCH',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ id, action: 'dislike', wallet: address }),
+        });
+        console.log(`Likes: ${data.likes}  Dislikes: ${data.dislikes}`);
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+// ─── ui-comment ───
+program
+    .command('ui-comment <id>')
+    .description('Comment on a generated UI')
+    .requiredOption('-m, --message <text>', 'Comment text')
+    .option('-k, --key <privateKey>', 'Wallet private key')
+    .action(async (id, opts) => {
+    try {
+        const { address } = getWallet(opts);
+        const data = await fetchJson(`${API_BASE}/api/ai/generate-ui`, {
+            method: 'PATCH',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ id, action: 'comment', wallet: address, comment: opts.message }),
+        });
+        console.log(`Comments: ${(data.comments || []).length}`);
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+// ─── ui-free-check ───
+program
+    .command('ui-free-check')
+    .description('Check free-tier UI generation eligibility')
+    .option('-k, --key <privateKey>', 'Wallet private key')
+    .action(async (opts) => {
+    try {
+        const { address } = getWallet(opts);
+        const params = new URLSearchParams({ checkFree: '1', wallet: address });
+        const data = await fetchJson(`${API_BASE}/api/ai/generate-ui?${params}`);
+        console.log(`\n  Wallet:     ${address}`);
+        console.log(`  Free tier:  ${data.free ? 'YES' : 'NO'}`);
+        console.log(`  Remaining:  ${data.remaining === Infinity ? '∞' : data.remaining}\n`);
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
 // ─── factory-balance ───
 program
     .command('factory-balance')

package/dist/index.d.ts

@@ -23,6 +23,36 @@ export interface ApinowConfig {
     baseUrl?: string;
     fetch?: typeof globalThis.fetch;
 }
+export interface GenerateUIOptions {
+    endpointName: string;
+    namespace: string;
+    description?: string;
+    querySchema?: any;
+    responseSchema?: any;
+    examples?: any[];
+    customPrompt?: string;
+}
+export interface GeneratedUI {
+    _id: string;
+    endpointKey: string;
+    endpointName: string;
+    namespace: string;
+    source: Record<string, string> | null;
+    status: 'generating' | 'complete' | 'error';
+    errorMessage?: string;
+    customPrompt: string;
+    model: string;
+    generatedBy: string | null;
+    openCount: number;
+    likes: string[];
+    dislikes: string[];
+    comments: Array<{
+        wallet: string;
+        text: string;
+        createdAt: string;
+    }>;
+    createdAt: string;
+}
 export declare function createClient(config: ApinowConfig): {
     wallet: `0x${string}`;
     /**
@@ -202,6 +232,48 @@ export declare function createClient(config: ApinowConfig): {
         testOutput: any;
         workflow: any;
     }>;
+    /**
+     * Start generating an AI UI for an endpoint. Returns immediately with a doc ID.
+     * Poll with getGeneratedUI() or use generateUIAndWait() for convenience.
+     */
+    generateUI(opts: GenerateUIOptions): Promise<{
+        id: string;
+        status: string;
+    }>;
+    /**
+     * Get a generated UI by ID (use to poll status after generateUI).
+     */
+    getGeneratedUI(id: string): Promise<GeneratedUI>;
+    /**
+     * List generated UIs for an endpoint.
+     */
+    listGeneratedUIs(endpointKey: string, sort?: "popular" | "recent"): Promise<{
+        uis: GeneratedUI[];
+    }>;
+    /**
+     * Check free-tier UI generation eligibility for a wallet.
+     */
+    checkFreeUI(): Promise<{
+        free: boolean;
+        remaining: number;
+    }>;
+    /**
+     * Like, dislike, or comment on a generated UI.
+     */
+    reactToUI(id: string, action: "like" | "dislike" | "comment", comment?: string): Promise<any>;
+    /**
+     * Delete a generated UI (must be creator or admin).
+     */
+    deleteGeneratedUI(id: string): Promise<{
+        deleted: boolean;
+    }>;
+    /**
+     * Generate a UI and poll until complete or error. Returns the final GeneratedUI doc.
+     * @param opts - generation params
+     * @param pollIntervalMs - polling interval (default 3000ms)
+     * @param timeoutMs - max wait time (default 120000ms)
+     */
+    generateUIAndWait(opts: GenerateUIOptions, pollIntervalMs?: number, timeoutMs?: number): Promise<GeneratedUI>;
     /**
      * Discover the x402 price for any external URL without executing it.
      * Free — no payment required.

package/dist/index.js

@@ -343,6 +343,106 @@ export function createClient(config) {
             }
             return { draft, endpoint, testOutput, workflow };
         },
+        // ─── AI UI Generation ───
+        /**
+         * Start generating an AI UI for an endpoint. Returns immediately with a doc ID.
+         * Poll with getGeneratedUI() or use generateUIAndWait() for convenience.
+         */
+        async generateUI(opts) {
+            const res = await fetch(`${baseUrl}/api/ai/generate-ui`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ ...opts, walletAddress: account.address }),
+            });
+            if (!res.ok) {
+                const text = await res.text();
+                throw new Error(`Failed to generate UI: ${res.status} ${text}`);
+            }
+            return res.json();
+        },
+        /**
+         * Get a generated UI by ID (use to poll status after generateUI).
+         */
+        async getGeneratedUI(id) {
+            const res = await fetch(`${baseUrl}/api/ai/generate-ui?id=${encodeURIComponent(id)}`);
+            if (!res.ok) {
+                const text = await res.text();
+                throw new Error(`Failed to get generated UI: ${res.status} ${text}`);
+            }
+            return res.json();
+        },
+        /**
+         * List generated UIs for an endpoint.
+         */
+        async listGeneratedUIs(endpointKey, sort = 'popular') {
+            const params = new URLSearchParams({ endpointKey, sort });
+            const res = await fetch(`${baseUrl}/api/ai/generate-ui?${params}`);
+            if (!res.ok) {
+                const text = await res.text();
+                throw new Error(`Failed to list generated UIs: ${res.status} ${text}`);
+            }
+            return res.json();
+        },
+        /**
+         * Check free-tier UI generation eligibility for a wallet.
+         */
+        async checkFreeUI() {
+            const params = new URLSearchParams({ checkFree: '1', wallet: account.address });
+            const res = await fetch(`${baseUrl}/api/ai/generate-ui?${params}`);
+            if (!res.ok)
+                throw new Error(`Failed to check free tier: ${res.status}`);
+            return res.json();
+        },
+        /**
+         * Like, dislike, or comment on a generated UI.
+         */
+        async reactToUI(id, action, comment) {
+            const body = { id, action, wallet: account.address };
+            if (comment)
+                body.comment = comment;
+            const res = await fetch(`${baseUrl}/api/ai/generate-ui`, {
+                method: 'PATCH',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(body),
+            });
+            if (!res.ok) {
+                const text = await res.text();
+                throw new Error(`Failed to react to UI: ${res.status} ${text}`);
+            }
+            return res.json();
+        },
+        /**
+         * Delete a generated UI (must be creator or admin).
+         */
+        async deleteGeneratedUI(id) {
+            const res = await fetch(`${baseUrl}/api/ai/generate-ui`, {
+                method: 'DELETE',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ id, wallet: account.address }),
+            });
+            if (!res.ok) {
+                const text = await res.text();
+                throw new Error(`Failed to delete UI: ${res.status} ${text}`);
+            }
+            return res.json();
+        },
+        /**
+         * Generate a UI and poll until complete or error. Returns the final GeneratedUI doc.
+         * @param opts - generation params
+         * @param pollIntervalMs - polling interval (default 3000ms)
+         * @param timeoutMs - max wait time (default 120000ms)
+         */
+        async generateUIAndWait(opts, pollIntervalMs = 3000, timeoutMs = 120000) {
+            const { id } = await this.generateUI(opts);
+            const deadline = Date.now() + timeoutMs;
+            while (Date.now() < deadline) {
+                await new Promise((r) => setTimeout(r, pollIntervalMs));
+                const doc = await this.getGeneratedUI(id);
+                if (doc.status === 'complete' || doc.status === 'error')
+                    return doc;
+            }
+            throw new Error(`UI generation timed out after ${timeoutMs / 1000}s (id: ${id})`);
+        },
         // ─── External x402 Proxy ───
         /**
          * Discover the x402 price for any external URL without executing it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apinow-sdk",
-  "version": "0.22.0",
+  "version": "0.23.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",