apinow-sdk 0.24.0 → 0.27.0

package/README.md

@@ -59,9 +59,18 @@ Returns:
 | `discoverPrice(url, method?)` | Discover the x402 price of any URL (free) |
 | `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) |
+| `listWorkflows(opts?)` | List workflows (filter by `creator`, `status`) |
+| `listMyWorkflows(opts?)` | List workflows created by your wallet |
+| `getWorkflow(id)` | Get workflow details (incl. `currentVersion`, `creatorWallet`) |
+| `createWorkflow(config)` | Create a workflow (seeds v1) |
+| `updateWorkflow(id, updates)` | Update a workflow (auto-bumps version on graph/price/splits change) |
+| `deleteWorkflow(id)` | Delete a workflow |
 | `runWorkflow(id, input)` | Run a workflow with automatic x402 payment |
+| `listWorkflowVersions(id)` | List versions (free) |
+| `getWorkflowVersion(id, vid)` | Get a specific version |
+| `createWorkflowVersion(id, updates)` | Creator — new version, defaults to active |
+| `setDefaultWorkflowVersion(id, vid)` | Promote/rollback a version |
+| `deleteWorkflowVersion(id, vid)` | Delete a non-default version |
 | `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 |
@@ -74,22 +83,44 @@ Returns:
 
 ### Workflows
 
-Workflows chain multiple x402 endpoints into a single paid DAG pipeline with automatic payment splitting.
+Workflows chain multiple x402 endpoints into a single paid DAG pipeline with automatic payment splitting. Each workflow is owned by a `creatorWallet` and tracks an immutable version history.
 
 ```typescript
-// list workflows
-const { workflows } = await apinow.listWorkflows({ status: 'active', limit: 10 });
+// list workflows (optionally filter by creator)
+const { workflows } = await apinow.listWorkflows({ creator: '0x...', status: 'active' });
 
-// get workflow details (nodes, splits, pricing)
-const workflow = await apinow.getWorkflow('90931d9c8fb94df9');
-console.log(workflow.name, workflow.totalPrice, workflow.graph.nodes);
+// your own workflows
+const mine = await apinow.listMyWorkflows();
+
+// get workflow details (nodes, splits, pricing, currentVersion, creatorWallet)
+const workflow = await apinow.getWorkflow('f5d40784593aa972');
 
 // run a workflow — x402 payment covers all nodes + creator split
-const result = await apinow.runWorkflow('90931d9c8fb94df9', {
+const result = await apinow.runWorkflow('f5d40784593aa972', {
   query: 'birthday gift ideas for a friend who loves cooking',
 });
 ```
 
+#### Versions & metadata cooldown
+
+- `PUT /api/workflows/{id}` with changes to `graph`, `totalPrice`, or `splits` auto-creates a new version.
+- `name` and `description` can only change **once every 7 days** per workflow (server returns `429` with `retryAfterMs`).
+- To iterate freely, create a new version — no cooldown.
+
+```typescript
+// snapshot history
+const { versions } = await apinow.listWorkflowVersions('f5d40784593aa972');
+
+// bump price without renaming
+await apinow.createWorkflowVersion('f5d40784593aa972', {
+  totalPrice: '0.12',
+  changelog: 'Raised price after usage spike',
+});
+
+// rollback
+await apinow.setDefaultWorkflowVersion('f5d40784593aa972', 1);
+```
+
 ### AI UI Generation
 
 Generate interactive Arrow JS sandbox UIs for any endpoint — ideal for AI agents that need a visual interface.

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.24.0');
+    .version('0.27.0');
 // ─── Helpers ───
 function getPrivateKey(opts) {
     const raw = opts.key || process.env.APINOW_WALLET_PKEY || process.env.PRIVATE_KEY;
@@ -48,8 +48,14 @@ function getWallet(opts) {
     const account = privateKeyToAccount(privateKey);
     return { privateKey, address: account.address };
 }
-function walletHeaders(address) {
-    return { 'Content-Type': 'application/json', 'x-wallet-address': address };
+/**
+ * Signed headers for mutating calls. The backend verifies the signature
+ * recovers to the claimed wallet address before accepting the request.
+ */
+async function walletHeaders(privateKey) {
+    const apinow = createClient({ privateKey });
+    const auth = await apinow.signAuthHeader();
+    return { 'Content-Type': 'application/json', ...auth };
 }
 // ─── search ───
 program
@@ -207,7 +213,7 @@ program
     .option('-k, --key <privateKey>', 'Wallet private key')
     .action(async (opts) => {
     try {
-        const { address } = getWallet(opts);
+        const { privateKey, address } = getWallet(opts);
         const body = {
             namespace: opts.namespace,
             endpointName: opts.name,
@@ -218,7 +224,7 @@ program
         };
         const data = await fetchJson(`${API_BASE}/api/endpoints`, {
             method: 'POST',
-            headers: walletHeaders(address),
+            headers: await walletHeaders(privateKey),
             body: JSON.stringify(body),
         });
         console.log(JSON.stringify(data, null, 2));
@@ -239,7 +245,7 @@ program
     .option('-k, --key <privateKey>', 'Wallet private key')
     .action(async (id, opts) => {
     try {
-        const { address } = getWallet(opts);
+        const { privateKey, address } = getWallet(opts);
         const body = {};
         if (opts.description)
             body.description = opts.description;
@@ -251,7 +257,7 @@ program
             body.paymentOptions = [{ usdAmount: opts.price, amount: opts.price }];
         const data = await fetchJson(`${API_BASE}/api/endpoints/${id}`, {
             method: 'PUT',
-            headers: walletHeaders(address),
+            headers: await walletHeaders(privateKey),
             body: JSON.stringify(body),
         });
         console.log(JSON.stringify(data, null, 2));
@@ -268,10 +274,10 @@ program
     .option('-k, --key <privateKey>', 'Wallet private key')
     .action(async (id, opts) => {
     try {
-        const { address } = getWallet(opts);
+        const { privateKey, address } = getWallet(opts);
         const data = await fetchJson(`${API_BASE}/api/endpoints/${id}`, {
             method: 'DELETE',
-            headers: walletHeaders(address),
+            headers: await walletHeaders(privateKey),
         });
         console.log(JSON.stringify(data, null, 2));
     }
@@ -425,6 +431,7 @@ program
         console.log(`  ${data.description || '(no description)'}\n`);
         console.log(`  ID:      ${data.workflowId}`);
         console.log(`  Status:  ${data.status}`);
+        console.log(`  Version: v${data.currentVersion ?? 1}${data.currentVersionId ? ` (${data.currentVersionId.slice(0, 8)}…)` : ''}`);
         console.log(`  Cost:    $${data.totalPrice} USDC`);
         console.log(`  Chain:   ${data.chain || 'base'}`);
         console.log(`  Creator: ${data.creatorWallet}`);
@@ -486,7 +493,7 @@ program
     .option('-k, --key <privateKey>', 'Wallet private key')
     .action(async (opts) => {
     try {
-        const { address } = getWallet(opts);
+        const { privateKey, address } = getWallet(opts);
         const body = { name: opts.name, totalPrice: opts.price };
         if (opts.description)
             body.description = opts.description;
@@ -498,7 +505,7 @@ program
             body.splits = JSON.parse(opts.splits);
         const data = await fetchJson(`${API_BASE}/api/workflows`, {
             method: 'POST',
-            headers: walletHeaders(address),
+            headers: await walletHeaders(privateKey),
             body: JSON.stringify(body),
         });
         console.log(JSON.stringify(data, null, 2));
@@ -519,7 +526,7 @@ program
     .option('-k, --key <privateKey>', 'Wallet private key')
     .action(async (id, opts) => {
     try {
-        const { address } = getWallet(opts);
+        const { privateKey, address } = getWallet(opts);
         const body = {};
         if (opts.name)
             body.name = opts.name;
@@ -531,7 +538,7 @@ program
             body.totalPrice = opts.price;
         const data = await fetchJson(`${API_BASE}/api/workflows/${id}`, {
             method: 'PUT',
-            headers: walletHeaders(address),
+            headers: await walletHeaders(privateKey),
             body: JSON.stringify(body),
         });
         console.log(JSON.stringify(data, null, 2));
@@ -548,10 +555,154 @@ program
     .option('-k, --key <privateKey>', 'Wallet private key')
     .action(async (id, opts) => {
     try {
-        const { address } = getWallet(opts);
+        const { privateKey, address } = getWallet(opts);
         const data = await fetchJson(`${API_BASE}/api/workflows/${id}`, {
             method: 'DELETE',
-            headers: walletHeaders(address),
+            headers: await walletHeaders(privateKey),
+        });
+        console.log(JSON.stringify(data, null, 2));
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+// ─── my-workflows (creator endpoint view) ───
+program
+    .command('my-workflows')
+    .description('List workflows you created (uses your wallet)')
+    .option('-l, --limit <n>', 'Max results', '50')
+    .option('-s, --status <status>', 'Filter: active | draft | paused | all', 'all')
+    .option('-k, --key <privateKey>', 'Wallet private key')
+    .action(async (opts) => {
+    try {
+        const { privateKey, address } = getWallet(opts);
+        const params = new URLSearchParams({
+            limit: opts.limit,
+            status: opts.status,
+            creator: address,
+        });
+        const data = await fetchJson(`${API_BASE}/api/workflows?${params}`);
+        const workflows = data.workflows || [];
+        if (!workflows.length) {
+            console.log('No workflows found for this wallet.');
+            return;
+        }
+        const rows = [['ID', 'NAME', 'STATUS', 'VER', 'NODES', 'COST']];
+        for (const w of workflows) {
+            rows.push([
+                w.workflowId,
+                truncate(w.name || '', 24),
+                w.status,
+                `v${w.currentVersion ?? 1}`,
+                String(w.graph?.nodes?.length || 0),
+                `$${w.totalPrice}`,
+            ]);
+        }
+        printTable(rows);
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+// ─── workflow-versions ───
+program
+    .command('workflow-versions <id>')
+    .description('List all versions of a workflow')
+    .action(async (id) => {
+    try {
+        const data = await fetchJson(`${API_BASE}/api/workflows/${id}/versions`);
+        const versions = data.versions || [];
+        if (!versions.length) {
+            console.log('No versions found.');
+            return;
+        }
+        const rows = [['VER', 'DEFAULT', 'VERSION_ID', 'PRICE', 'CREATED', 'CHANGELOG']];
+        for (const v of versions) {
+            rows.push([
+                `v${v.version}`,
+                v.isDefault ? '★' : '',
+                v.versionId,
+                `$${v.totalPrice}`,
+                new Date(v.createdAt).toLocaleDateString(),
+                truncate(v.changelog || '', 40),
+            ]);
+        }
+        printTable(rows);
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+// ─── workflow-version-create ───
+program
+    .command('workflow-version-create <id>')
+    .description('Create a new version of a workflow (graph/price/splits)')
+    .option('--graph <json>', 'Graph JSON (inherits current if omitted)')
+    .option('--price <usdc>', 'Total price')
+    .option('--splits <json>', 'Splits JSON array')
+    .option('--changelog <msg>', 'Changelog message')
+    .option('--no-default', 'Create as non-default (keeps current version active)')
+    .option('-k, --key <privateKey>', 'Wallet private key')
+    .action(async (id, opts) => {
+    try {
+        const { privateKey, address } = getWallet(opts);
+        const body = {};
+        if (opts.graph)
+            body.graph = JSON.parse(opts.graph);
+        if (opts.price)
+            body.totalPrice = opts.price;
+        if (opts.splits)
+            body.splits = JSON.parse(opts.splits);
+        if (opts.changelog)
+            body.changelog = opts.changelog;
+        if (opts.default === false)
+            body.setDefault = false;
+        const data = await fetchJson(`${API_BASE}/api/workflows/${id}/versions`, {
+            method: 'POST',
+            headers: await walletHeaders(privateKey),
+            body: JSON.stringify(body),
+        });
+        console.log(JSON.stringify(data, null, 2));
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+// ─── workflow-version-set-default ───
+program
+    .command('workflow-version-set-default <id> <versionIdOrNumber>')
+    .description('Set a version as the active/default for a workflow (rollback/promote)')
+    .option('-k, --key <privateKey>', 'Wallet private key')
+    .action(async (id, vid, opts) => {
+    try {
+        const { privateKey, address } = getWallet(opts);
+        const data = await fetchJson(`${API_BASE}/api/workflows/${id}/versions/${vid}`, {
+            method: 'PUT',
+            headers: await walletHeaders(privateKey),
+            body: JSON.stringify({ setDefault: true }),
+        });
+        console.log(JSON.stringify(data, null, 2));
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+// ─── workflow-version-delete ───
+program
+    .command('workflow-version-delete <id> <versionIdOrNumber>')
+    .description('Delete a non-default workflow version')
+    .option('-k, --key <privateKey>', 'Wallet private key')
+    .action(async (id, vid, opts) => {
+    try {
+        const { privateKey, address } = getWallet(opts);
+        const data = await fetchJson(`${API_BASE}/api/workflows/${id}/versions/${vid}`, {
+            method: 'DELETE',
+            headers: await walletHeaders(privateKey),
         });
         console.log(JSON.stringify(data, null, 2));
     }
@@ -573,7 +724,7 @@ program
         if (!endpoint.includes('/'))
             throw new Error('Format: namespace/endpoint-name');
         const [ns, ep] = endpoint.split('/');
-        const { address } = getWallet(opts);
+        const { privateKey, address } = getWallet(opts);
         const details = await fetchJson(`${API_BASE}/api/endpoints/${ns}/${ep}/details`);
         const body = {
             endpointName: ep,
@@ -693,7 +844,7 @@ program
     .option('-k, --key <privateKey>', 'Wallet private key')
     .action(async (id, opts) => {
     try {
-        const { address } = getWallet(opts);
+        const { privateKey, address } = getWallet(opts);
         const data = await fetchJson(`${API_BASE}/api/ai/generate-ui`, {
             method: 'DELETE',
             headers: { 'Content-Type': 'application/json' },
@@ -713,7 +864,7 @@ program
     .option('-k, --key <privateKey>', 'Wallet private key')
     .action(async (id, opts) => {
     try {
-        const { address } = getWallet(opts);
+        const { privateKey, address } = getWallet(opts);
         const data = await fetchJson(`${API_BASE}/api/ai/generate-ui`, {
             method: 'PATCH',
             headers: { 'Content-Type': 'application/json' },
@@ -732,7 +883,7 @@ program
     .option('-k, --key <privateKey>', 'Wallet private key')
     .action(async (id, opts) => {
     try {
-        const { address } = getWallet(opts);
+        const { privateKey, address } = getWallet(opts);
         const data = await fetchJson(`${API_BASE}/api/ai/generate-ui`, {
             method: 'PATCH',
             headers: { 'Content-Type': 'application/json' },
@@ -753,7 +904,7 @@ program
     .option('-k, --key <privateKey>', 'Wallet private key')
     .action(async (id, opts) => {
     try {
-        const { address } = getWallet(opts);
+        const { privateKey, address } = getWallet(opts);
         const data = await fetchJson(`${API_BASE}/api/ai/generate-ui`, {
             method: 'PATCH',
             headers: { 'Content-Type': 'application/json' },
@@ -773,7 +924,7 @@ program
     .option('-k, --key <privateKey>', 'Wallet private key')
     .action(async (opts) => {
     try {
-        const { address } = getWallet(opts);
+        const { privateKey, 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}`);
@@ -792,9 +943,9 @@ program
     .option('-k, --key <privateKey>', 'Wallet private key')
     .action(async (opts) => {
     try {
-        const { address } = getWallet(opts);
+        const { privateKey, address } = getWallet(opts);
         const data = await fetchJson(`${API_BASE}/api/user-factory/check-balance`, {
-            headers: walletHeaders(address),
+            headers: await walletHeaders(privateKey),
         });
         console.log(`\n  Wallet:   ${address}`);
         console.log(`  Balance:  ${data.balance} $APINOW`);
@@ -813,9 +964,9 @@ program
     .option('-k, --key <privateKey>', 'Wallet private key')
     .action(async (opts) => {
     try {
-        const { address } = getWallet(opts);
+        const { privateKey, address } = getWallet(opts);
         const data = await fetchJson(`${API_BASE}/api/user-factory`, {
-            headers: walletHeaders(address),
+            headers: await walletHeaders(privateKey),
         });
         const endpoints = data.endpoints || [];
         if (!endpoints.length) {
@@ -845,11 +996,11 @@ program
     .option('-k, --key <privateKey>', 'Wallet private key')
     .action(async (idea, opts) => {
     try {
-        const { address } = getWallet(opts);
+        const { privateKey, address } = getWallet(opts);
         console.error('Generating endpoint config…');
         const data = await fetchJson(`${API_BASE}/api/user-factory/generate`, {
             method: 'POST',
-            headers: walletHeaders(address),
+            headers: await walletHeaders(privateKey),
             body: JSON.stringify({ idea }),
         });
         console.log(JSON.stringify(data, null, 2));
@@ -876,7 +1027,7 @@ program
     .option('-k, --key <privateKey>', 'Wallet private key')
     .action(async (opts) => {
     try {
-        const { address } = getWallet(opts);
+        const { privateKey, address } = getWallet(opts);
         let body;
         if (opts.fromJson) {
             const { readFileSync } = await import('fs');
@@ -933,7 +1084,7 @@ program
         console.error(`Creating endpoint "${body.name}"…`);
         const data = await fetchJson(`${API_BASE}/api/user-factory`, {
             method: 'POST',
-            headers: walletHeaders(address),
+            headers: await walletHeaders(privateKey),
             body: JSON.stringify(body),
         });
         const ep = data.endpoint;
@@ -961,7 +1112,7 @@ program
     .option('-k, --key <privateKey>', 'Wallet private key')
     .action(async (endpointId, opts) => {
     try {
-        const { address } = getWallet(opts);
+        const { privateKey, address } = getWallet(opts);
         const body = { endpointId, markupPercent: Number(opts.markup) };
         if (opts.name)
             body.workflowName = opts.name;
@@ -977,7 +1128,7 @@ program
         console.error(`Creating markup workflow (${opts.markup}%${tbLabel})…`);
         const data = await fetchJson(`${API_BASE}/api/user-factory/markup`, {
             method: 'POST',
-            headers: walletHeaders(address),
+            headers: await walletHeaders(privateKey),
             body: JSON.stringify(body),
         });
         const w = data.workflow;
@@ -1006,7 +1157,7 @@ program
     try {
         if (!endpoint.includes('/'))
             throw new Error('Format: namespace/endpoint-name');
-        const { address } = getWallet(opts);
+        const { privateKey, address } = getWallet(opts);
         const [namespace, endpointName] = endpoint.split('/');
         const body = { namespace, endpointName };
         if (opts.data)
@@ -1016,7 +1167,7 @@ program
         console.error(`Testing ${endpoint}…`);
         const data = await fetchJson(`${API_BASE}/api/user-factory/test-call`, {
             method: 'POST',
-            headers: walletHeaders(address),
+            headers: await walletHeaders(privateKey),
             body: JSON.stringify(body),
         });
         console.log(JSON.stringify(data.output, null, 2));
@@ -1044,12 +1195,12 @@ program
     .option('-k, --key <privateKey>', 'Wallet private key')
     .action(async (idea, opts) => {
     try {
-        const { address } = getWallet(opts);
+        const { privateKey, address } = getWallet(opts);
         // Step 1: Generate
         console.error('Step 1/4: Generating endpoint config from idea…');
         const draft = await fetchJson(`${API_BASE}/api/user-factory/generate`, {
             method: 'POST',
-            headers: walletHeaders(address),
+            headers: await walletHeaders(privateKey),
             body: JSON.stringify({ idea }),
         });
         console.error(`  → ${draft.name}: ${draft.description}`);
@@ -1075,7 +1226,7 @@ program
             createBody.recipientWallet = opts.recipient;
         const createData = await fetchJson(`${API_BASE}/api/user-factory`, {
             method: 'POST',
-            headers: walletHeaders(address),
+            headers: await walletHeaders(privateKey),
             body: JSON.stringify(createBody),
         });
         const ep = createData.endpoint;
@@ -1085,7 +1236,7 @@ program
         const testInput = draft.exampleInput || { prompt: 'test' };
         const testData = await fetchJson(`${API_BASE}/api/user-factory/test-call`, {
             method: 'POST',
-            headers: walletHeaders(address),
+            headers: await walletHeaders(privateKey),
             body: JSON.stringify({
                 namespace: ep.namespace,
                 endpointName: ep.endpointName,
@@ -1112,7 +1263,7 @@ program
                 markupBody.tokenBuyCA = opts.tokenBuyCa;
             const markupData = await fetchJson(`${API_BASE}/api/user-factory/markup`, {
                 method: 'POST',
-                headers: walletHeaders(address),
+                headers: await walletHeaders(privateKey),
                 body: JSON.stringify(markupBody),
             });
             workflow = markupData.workflow;

package/dist/index.d.ts

@@ -18,11 +18,31 @@ export interface PriceDiscovery {
     network: string;
     upstreamAccepts: any[];
 }
-export interface ApinowConfig {
+/**
+ * Agent/server path — signs everything with a raw private key. Enables
+ * both x402 paid calls and signed-auth write calls.
+ */
+export interface ApinowServerConfig {
     privateKey: `0x${string}`;
     baseUrl?: string;
     fetch?: typeof globalThis.fetch;
 }
+/**
+ * Browser/wallet path — you provide a `signer` (any EIP-191 `personal_sign`
+ * function, e.g. from wagmi's `walletClient.signMessage`) and the connected
+ * `address`. Enables signed-auth writes. Paid x402 calls are NOT provided by
+ * this path — construct the x402 fetch yourself (see useX402Fetch pattern in
+ * the skill docs) and pass it to `paidFetch` if you need unified behaviour.
+ */
+export interface ApinowBrowserConfig {
+    signer: (message: string) => Promise<`0x${string}` | string>;
+    address: `0x${string}`;
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+    /** Optional externally-prepared x402 fetch for paid calls. */
+    paidFetch?: typeof globalThis.fetch;
+}
+export type ApinowConfig = ApinowServerConfig | ApinowBrowserConfig;
 export interface GenerateUIOptions {
     endpointName: string;
     namespace: string;
@@ -55,6 +75,11 @@ export interface GeneratedUI {
 }
 export declare function createClient(config: ApinowConfig): {
     wallet: `0x${string}`;
+    /**
+     * Produce a signed `Authorization` header for custom write calls.
+     * Pairs with `x-wallet-address`. Backend accepts msg within ~10 min.
+     */
+    signAuthHeader: () => Promise<Record<string, string>>;
     /**
      * Call any APINow endpoint. Handles x402 payment automatically.
      *
@@ -138,6 +163,52 @@ export declare function createClient(config: ApinowConfig): {
     }): Promise<any>;
     updateWorkflow(workflowId: string, updates: Record<string, any>): Promise<any>;
     deleteWorkflow(workflowId: string): Promise<any>;
+    /**
+     * List workflows you created (convenience for `listWorkflows({ creator: yourWallet })`).
+     */
+    listMyWorkflows(opts?: {
+        status?: string;
+        limit?: number;
+    }): Promise<any>;
+    /**
+     * List all versions of a workflow (public, free).
+     */
+    listWorkflowVersions(workflowId: string): Promise<{
+        versions: any[];
+    }>;
+    /**
+     * Get a specific workflow version by versionId or numeric version.
+     */
+    getWorkflowVersion(workflowId: string, versionIdOrNumber: string | number): Promise<any>;
+    /**
+     * Create a new workflow version (creator only). Defaults to setting it as default.
+     * Omit fields to inherit from current workflow.
+     */
+    createWorkflowVersion(workflowId: string, updates?: {
+        graph?: {
+            nodes: any[];
+            outputNode: string;
+            outputMapping?: any;
+        };
+        totalPrice?: string;
+        splits?: Array<{
+            address: string;
+            basisPoints: number;
+            label?: string;
+            tokenAddress?: string;
+        }>;
+        mermaidDiagram?: string;
+        executionMode?: "balanced" | "optimistic" | "settle_first";
+        changelog?: string;
+        setDefault?: boolean;
+        forkedFrom?: string;
+    }): Promise<any>;
+    /**
+     * Set a version as the default (active) for a workflow. Also rolls the
+     * workflow's graph/price/splits back to that version's snapshot.
+     */
+    setDefaultWorkflowVersion(workflowId: string, versionIdOrNumber: string | number): Promise<any>;
+    deleteWorkflowVersion(workflowId: string, versionIdOrNumber: string | number): Promise<any>;
     /**
      * Run a workflow. Handles x402 payment automatically.
      *

package/dist/index.js

@@ -2,6 +2,9 @@ import { x402Client, wrapFetchWithPayment } from '@x402/fetch';
 import { registerExactEvmScheme } from '@x402/evm/exact/client';
 import { privateKeyToAccount } from 'viem/accounts';
 const APINOW_BASE = 'https://apinow.fun';
+function isServerConfig(c) {
+    return 'privateKey' in c && typeof c.privateKey === 'string';
+}
 // ─── SDK ───
 // Prevent undici (Node 20+ / Vercel) from crashing when @x402/fetch retries
 // a POST with a cloned Request body stream and the server returns a 3xx redirect.
@@ -23,18 +26,83 @@ async function followRedirects(res) {
     return res;
 }
 export function createClient(config) {
-    const { privateKey, baseUrl = APINOW_BASE, fetch: customFetch } = config;
-    const account = privateKeyToAccount(privateKey);
-    const client = new x402Client();
-    registerExactEvmScheme(client, { signer: account });
-    const safeFetch = makeSafeFetch(customFetch ?? fetch);
-    const rawFetchWithPayment = wrapFetchWithPayment(safeFetch, client);
-    const fetchWithPayment = (async (input, init) => {
-        const res = await rawFetchWithPayment(input, init);
-        return followRedirects(res);
-    });
+    const server = isServerConfig(config);
+    const baseUrl = config.baseUrl ?? APINOW_BASE;
+    const customFetch = config.fetch;
+    // Resolve address + signer from whichever config shape the caller passed.
+    const account = server ? privateKeyToAccount(config.privateKey) : null;
+    const address = server
+        ? account.address
+        : config.address.toLowerCase();
+    const signMessage = server
+        ? (msg) => account.signMessage({ message: msg })
+        : (msg) => Promise.resolve(config.signer(msg)).then((s) => String(s));
+    // x402 paid fetch — only available when a private key is provided. Browsers
+    // should build their own x402 fetch (see skill.md useX402Fetch) and pass it
+    // as `paidFetch` to fall back through here.
+    const paidFetchExternal = !server ? config.paidFetch : undefined;
+    const fetchWithPayment = server
+        ? (() => {
+            const client = new x402Client();
+            registerExactEvmScheme(client, { signer: account });
+            const safeFetch = makeSafeFetch(customFetch ?? fetch);
+            const rawFetchWithPayment = wrapFetchWithPayment(safeFetch, client);
+            return (async (input, init) => {
+                const res = await rawFetchWithPayment(input, init);
+                return followRedirects(res);
+            });
+        })()
+        : (paidFetchExternal ??
+            (() => {
+                throw new Error('createClient: paid calls require a `privateKey` config or an explicit `paidFetch`. Pass an x402-wrapped fetch to make paid calls from the browser.');
+            }));
+    /**
+     * Produce an `Authorization: Bearer <msg>||<sig>||<addr>` header signed by
+     * the wallet. Backend verifies with ethers.recoverAddress and rejects
+     * messages older than ~10 min. Works for both server (privateKey) and
+     * browser (walletClient.signMessage) configs.
+     */
+    async function signAuthHeader() {
+        const issuedAt = new Date().toISOString();
+        const nonce = Math.random().toString(36).slice(2) + Date.now().toString(36);
+        const message = `APINow auth\naddress: ${address}\nissuedAt: ${issuedAt}\nnonce: ${nonce}`;
+        const signature = await signMessage(message);
+        return {
+            Authorization: `Bearer ${message}||${signature}||${address}`,
+            'x-wallet-address': address,
+        };
+    }
+    /**
+     * Fetch wrapper that signs write requests with the wallet private key.
+     * Use for any non-paid mutating API (endpoint/workflow/version CRUD).
+     */
+    async function authedFetch(url, init = {}) {
+        const authHeaders = await signAuthHeader();
+        const res = await fetch(url, {
+            ...init,
+            headers: {
+                ...(init.body ? { 'Content-Type': 'application/json' } : {}),
+                ...authHeaders,
+                ...init.headers,
+            },
+        });
+        return res;
+    }
+    async function authedJson(url, init = {}) {
+        const res = await authedFetch(url, init);
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`APINow ${res.status}: ${text}`);
+        }
+        return res.json();
+    }
     return {
-        wallet: account.address,
+        wallet: address,
+        /**
+         * Produce a signed `Authorization` header for custom write calls.
+         * Pairs with `x-wallet-address`. Backend accepts msg within ~10 min.
+         */
+        signAuthHeader,
         /**
          * Call any APINow endpoint. Handles x402 payment automatically.
          *
@@ -84,16 +152,10 @@ export function createClient(config) {
         },
         // ─── Endpoint CRUD ───
         async createEndpoint(config) {
-            const res = await fetch(`${baseUrl}/api/endpoints`, {
+            return authedJson(`${baseUrl}/api/endpoints`, {
                 method: 'POST',
-                headers: { 'Content-Type': 'application/json', 'x-wallet-address': account.address },
                 body: JSON.stringify(config),
             });
-            if (!res.ok) {
-                const text = await res.text();
-                throw new Error(`Failed to create endpoint: ${res.status} ${text}`);
-            }
-            return res.json();
         },
         async getEndpoint(id) {
             const res = await fetch(`${baseUrl}/api/endpoints/${id}`);
@@ -102,27 +164,13 @@ export function createClient(config) {
             return res.json();
         },
         async updateEndpoint(id, updates) {
-            const res = await fetch(`${baseUrl}/api/endpoints/${id}`, {
+            return authedJson(`${baseUrl}/api/endpoints/${id}`, {
                 method: 'PUT',
-                headers: { 'Content-Type': 'application/json', 'x-wallet-address': account.address },
                 body: JSON.stringify(updates),
             });
-            if (!res.ok) {
-                const text = await res.text();
-                throw new Error(`Failed to update endpoint: ${res.status} ${text}`);
-            }
-            return res.json();
         },
         async deleteEndpoint(id) {
-            const res = await fetch(`${baseUrl}/api/endpoints/${id}`, {
-                method: 'DELETE',
-                headers: { 'x-wallet-address': account.address },
-            });
-            if (!res.ok) {
-                const text = await res.text();
-                throw new Error(`Failed to delete endpoint: ${res.status} ${text}`);
-            }
-            return res.json();
+            return authedJson(`${baseUrl}/api/endpoints/${id}`, { method: 'DELETE' });
         },
         async listEndpoints(opts = {}) {
             const params = new URLSearchParams();
@@ -166,40 +214,68 @@ export function createClient(config) {
             return res.json();
         },
         async createWorkflow(config) {
-            const res = await fetch(`${baseUrl}/api/workflows`, {
+            return authedJson(`${baseUrl}/api/workflows`, {
                 method: 'POST',
-                headers: { 'Content-Type': 'application/json', 'x-wallet-address': account.address },
                 body: JSON.stringify(config),
             });
-            if (!res.ok) {
-                const text = await res.text();
-                throw new Error(`Failed to create workflow: ${res.status} ${text}`);
-            }
-            return res.json();
         },
         async updateWorkflow(workflowId, updates) {
-            const res = await fetch(`${baseUrl}/api/workflows/${workflowId}`, {
+            return authedJson(`${baseUrl}/api/workflows/${workflowId}`, {
                 method: 'PUT',
-                headers: { 'Content-Type': 'application/json', 'x-wallet-address': account.address },
                 body: JSON.stringify(updates),
             });
-            if (!res.ok) {
-                const text = await res.text();
-                throw new Error(`Failed to update workflow: ${res.status} ${text}`);
-            }
-            return res.json();
         },
         async deleteWorkflow(workflowId) {
-            const res = await fetch(`${baseUrl}/api/workflows/${workflowId}`, {
-                method: 'DELETE',
-                headers: { 'x-wallet-address': account.address },
-            });
-            if (!res.ok) {
-                const text = await res.text();
-                throw new Error(`Failed to delete workflow: ${res.status} ${text}`);
-            }
+            return authedJson(`${baseUrl}/api/workflows/${workflowId}`, { method: 'DELETE' });
+        },
+        /**
+         * List workflows you created (convenience for `listWorkflows({ creator: yourWallet })`).
+         */
+        async listMyWorkflows(opts = {}) {
+            return this.listWorkflows({ ...opts, creator: address });
+        },
+        // ─── Workflow Versions ───
+        /**
+         * List all versions of a workflow (public, free).
+         */
+        async listWorkflowVersions(workflowId) {
+            const res = await fetch(`${baseUrl}/api/workflows/${workflowId}/versions`);
+            if (!res.ok)
+                throw new Error(`Failed to list versions: ${res.status}`);
+            return res.json();
+        },
+        /**
+         * Get a specific workflow version by versionId or numeric version.
+         */
+        async getWorkflowVersion(workflowId, versionIdOrNumber) {
+            const res = await fetch(`${baseUrl}/api/workflows/${workflowId}/versions/${versionIdOrNumber}`);
+            if (!res.ok)
+                throw new Error(`Failed to get version: ${res.status}`);
             return res.json();
         },
+        /**
+         * Create a new workflow version (creator only). Defaults to setting it as default.
+         * Omit fields to inherit from current workflow.
+         */
+        async createWorkflowVersion(workflowId, updates = {}) {
+            return authedJson(`${baseUrl}/api/workflows/${workflowId}/versions`, {
+                method: 'POST',
+                body: JSON.stringify(updates),
+            });
+        },
+        /**
+         * Set a version as the default (active) for a workflow. Also rolls the
+         * workflow's graph/price/splits back to that version's snapshot.
+         */
+        async setDefaultWorkflowVersion(workflowId, versionIdOrNumber) {
+            return authedJson(`${baseUrl}/api/workflows/${workflowId}/versions/${versionIdOrNumber}`, {
+                method: 'PUT',
+                body: JSON.stringify({ setDefault: true }),
+            });
+        },
+        async deleteWorkflowVersion(workflowId, versionIdOrNumber) {
+            return authedJson(`${baseUrl}/api/workflows/${workflowId}/versions/${versionIdOrNumber}`, { method: 'DELETE' });
+        },
         /**
          * Run a workflow. Handles x402 payment automatically.
          *
@@ -217,82 +293,50 @@ export function createClient(config) {
          * Check $APINOW token balance and factory access.
          */
         async factoryBalance() {
-            const res = await fetch(`${baseUrl}/api/user-factory/check-balance`, {
-                headers: { 'x-wallet-address': account.address },
-            });
-            if (!res.ok)
-                throw new Error(`Failed to check balance: ${res.status}`);
-            return res.json();
+            return authedJson(`${baseUrl}/api/user-factory/check-balance`);
         },
         /**
          * List your user-factory endpoints.
          */
         async factoryList() {
-            const res = await fetch(`${baseUrl}/api/user-factory`, {
-                headers: { 'x-wallet-address': account.address },
-            });
-            if (!res.ok)
-                throw new Error(`Failed to list factory endpoints: ${res.status}`);
-            return res.json();
+            return authedJson(`${baseUrl}/api/user-factory`);
         },
         /**
          * Generate endpoint config from a natural-language idea.
          */
         async factoryGenerate(idea) {
-            const res = await fetch(`${baseUrl}/api/user-factory/generate`, {
+            return authedJson(`${baseUrl}/api/user-factory/generate`, {
                 method: 'POST',
-                headers: { 'Content-Type': 'application/json', 'x-wallet-address': account.address },
                 body: JSON.stringify({ idea }),
             });
-            if (!res.ok)
-                throw new Error(`Failed to generate: ${res.status}`);
-            return res.json();
         },
         /**
          * Create an LLM endpoint via user-factory.
          */
         async factoryCreate(config) {
-            const res = await fetch(`${baseUrl}/api/user-factory`, {
+            return authedJson(`${baseUrl}/api/user-factory`, {
                 method: 'POST',
-                headers: { 'Content-Type': 'application/json', 'x-wallet-address': account.address },
                 body: JSON.stringify(config),
             });
-            if (!res.ok) {
-                const text = await res.text();
-                throw new Error(`Failed to create endpoint: ${res.status} ${text}`);
-            }
-            return res.json();
         },
         /**
          * Create a markup workflow wrapping an existing endpoint.
          * Optionally allocate a portion of the markup to a token buy split.
          */
         async factoryMarkup(opts) {
-            const res = await fetch(`${baseUrl}/api/user-factory/markup`, {
+            return authedJson(`${baseUrl}/api/user-factory/markup`, {
                 method: 'POST',
-                headers: { 'Content-Type': 'application/json', 'x-wallet-address': account.address },
                 body: JSON.stringify(opts),
             });
-            if (!res.ok) {
-                const text = await res.text();
-                throw new Error(`Failed to create markup: ${res.status} ${text}`);
-            }
-            return res.json();
         },
         /**
          * Test-call an endpoint without payment (free, server-side LLM call).
          */
         async factoryTestCall(opts) {
-            const res = await fetch(`${baseUrl}/api/user-factory/test-call`, {
+            return authedJson(`${baseUrl}/api/user-factory/test-call`, {
                 method: 'POST',
-                headers: { 'Content-Type': 'application/json', 'x-wallet-address': account.address },
                 body: JSON.stringify(opts),
             });
-            if (!res.ok) {
-                const text = await res.text();
-                throw new Error(`Failed to test call: ${res.status} ${text}`);
-            }
-            return res.json();
         },
         // ─── Factory Pipeline ───
         /**
@@ -352,7 +396,7 @@ export function createClient(config) {
             const res = await fetch(`${baseUrl}/api/ai/generate-ui`, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({ ...opts, walletAddress: account.address }),
+                body: JSON.stringify({ ...opts, walletAddress: address }),
             });
             if (!res.ok) {
                 const text = await res.text();
@@ -387,7 +431,7 @@ export function createClient(config) {
          * Check free-tier UI generation eligibility for a wallet.
          */
         async checkFreeUI() {
-            const params = new URLSearchParams({ checkFree: '1', wallet: account.address });
+            const params = new URLSearchParams({ checkFree: '1', wallet: address });
             const res = await fetch(`${baseUrl}/api/ai/generate-ui?${params}`);
             if (!res.ok)
                 throw new Error(`Failed to check free tier: ${res.status}`);
@@ -397,7 +441,7 @@ export function createClient(config) {
          * Like, dislike, or comment on a generated UI.
          */
         async reactToUI(id, action, comment) {
-            const body = { id, action, wallet: account.address };
+            const body = { id, action, wallet: address };
             if (comment)
                 body.comment = comment;
             const res = await fetch(`${baseUrl}/api/ai/generate-ui`, {
@@ -418,7 +462,7 @@ export function createClient(config) {
             const res = await fetch(`${baseUrl}/api/ai/generate-ui`, {
                 method: 'DELETE',
                 headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({ id, wallet: account.address }),
+                body: JSON.stringify({ id, wallet: address }),
             });
             if (!res.ok) {
                 const text = await res.text();

package/package.json

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