apinow-sdk 0.26.0 → 0.28.0

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.26.0');
+    .version('0.27.0');
 // ─── Helpers ───
 function getPrivateKey(opts) {
     const raw = opts.key || process.env.APINOW_WALLET_PKEY || process.env.PRIVATE_KEY;
@@ -210,6 +210,7 @@ program
     .requiredOption('--description <desc>', 'Description')
     .option('--method <method>', 'HTTP method', 'POST')
     .option('--price <usdc>', 'USDC price per call', '0.01')
+    .option('--splits <json>', 'Splits JSON array [{address, basisPoints, label?, tokenAddress?}] — basisPoints must sum to 10000')
     .option('-k, --key <privateKey>', 'Wallet private key')
     .action(async (opts) => {
     try {
@@ -222,6 +223,8 @@ program
             httpMethod: opts.method.toUpperCase(),
             paymentOptions: [{ usdAmount: opts.price, amount: opts.price }],
         };
+        if (opts.splits)
+            body.splits = JSON.parse(opts.splits);
         const data = await fetchJson(`${API_BASE}/api/endpoints`, {
             method: 'POST',
             headers: await walletHeaders(privateKey),
@@ -242,6 +245,7 @@ program
     .option('--url <url>', 'New URL')
     .option('--price <usdc>', 'New USDC price')
     .option('--status <status>', 'New status')
+    .option('--splits <json>', 'Splits JSON array — changing splits redeploys the splitter contract (V2 is immutable)')
     .option('-k, --key <privateKey>', 'Wallet private key')
     .action(async (id, opts) => {
     try {
@@ -255,6 +259,8 @@ program
             body.status = opts.status;
         if (opts.price)
             body.paymentOptions = [{ usdAmount: opts.price, amount: opts.price }];
+        if (opts.splits)
+            body.splits = JSON.parse(opts.splits);
         const data = await fetchJson(`${API_BASE}/api/endpoints/${id}`, {
             method: 'PUT',
             headers: await walletHeaders(privateKey),
@@ -518,11 +524,13 @@ program
 // ─── workflow-update ───
 program
     .command('workflow-update <id>')
-    .description('Update a workflow by ID')
-    .option('--name <name>', 'New name')
-    .option('--description <desc>', 'New description')
+    .description('Update a workflow by ID (price/splits/graph changes auto-create a new version)')
+    .option('--name <name>', 'New name (7-day cooldown; 429 if on cooldown)')
+    .option('--description <desc>', 'New description (7-day cooldown)')
     .option('--status <status>', 'New status')
-    .option('--price <usdc>', 'New total price')
+    .option('--price <usdc>', 'New total price — auto-bumps version')
+    .option('--splits <json>', 'Splits JSON array — auto-bumps version; redeploys splitter if structurally changed')
+    .option('--changelog <msg>', 'Label for the auto-created version snapshot')
     .option('-k, --key <privateKey>', 'Wallet private key')
     .action(async (id, opts) => {
     try {
@@ -536,6 +544,10 @@ program
             body.status = opts.status;
         if (opts.price)
             body.totalPrice = opts.price;
+        if (opts.splits)
+            body.splits = JSON.parse(opts.splits);
+        if (opts.changelog)
+            body.changelog = opts.changelog;
         const data = await fetchJson(`${API_BASE}/api/workflows/${id}`, {
             method: 'PUT',
             headers: await walletHeaders(privateKey),

package/dist/index.d.ts

@@ -18,11 +18,50 @@ 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 SplitConfig {
+    address: string;
+    basisPoints: number;
+    label?: string;
+    tokenAddress?: string;
+    recipientAddress?: string;
+}
+/**
+ * Thrown by authed writes when the backend returns a non-2xx. Exposes status
+ * code and parsed JSON body so callers can branch on e.g. 429 cooldowns
+ * without re-parsing error text.
+ */
+export declare class ApinowApiError extends Error {
+    readonly status: number;
+    readonly body: any;
+    readonly retryAfterMs?: number;
+    readonly retryAfterDays?: number;
+    constructor(status: number, body: any);
+}
 export interface GenerateUIOptions {
     endpointName: string;
     namespace: string;
@@ -78,6 +117,13 @@ export declare function createClient(config: ApinowConfig): {
      * Get public endpoint info (free, no payment).
      */
     info(namespace: string, endpointName: string): Promise<any>;
+    /**
+     * Create an endpoint. If `splits` are provided they must sum to exactly
+     * `10000` basis points; the server deploys a 0xSplits V2 splitter after
+     * creation and stores `splitterAddress` on the endpoint. Non-fatal if
+     * the splitter deploy fails — endpoint will exist without one and can be
+     * retried via `updateEndpoint({ splits })`.
+     */
     createEndpoint(config: {
         namespace: string;
         endpointName: string;
@@ -96,9 +142,34 @@ export declare function createClient(config: ApinowConfig): {
         exampleQuery?: any;
         exampleOutput?: any;
         docsUrl?: string;
+        splits?: SplitConfig[];
     }): Promise<any>;
     getEndpoint(id: string): Promise<any>;
-    updateEndpoint(id: string, updates: Record<string, any>): Promise<any>;
+    /**
+     * Update an endpoint. Changing `splits` (structurally) redeploys the
+     * splitter contract (V2 is immutable); the old address is archived on
+     * `previousSplitters[]` and the platform drains leftover USDC from it.
+     * `splits` must sum to `10000` basis points when non-empty.
+     */
+    updateEndpoint(id: string, updates: {
+        url?: string;
+        description?: string;
+        httpMethod?: "GET" | "POST";
+        paymentOptions?: Array<{
+            amount?: string;
+            usdAmount?: string;
+            tokenAddress?: string;
+            tokenSymbol?: string;
+        }>;
+        status?: string;
+        splits?: SplitConfig[];
+        querySchema?: any;
+        responseSchema?: any;
+        exampleQuery?: any;
+        exampleOutput?: any;
+        docsUrl?: string;
+        [key: string]: any;
+    }): Promise<any>;
     deleteEndpoint(id: string): Promise<any>;
     listEndpoints(opts?: {
         limit?: number;
@@ -133,15 +204,32 @@ export declare function createClient(config: ApinowConfig): {
         };
         prompt?: string;
         totalPrice?: string;
-        splits?: Array<{
-            address: string;
-            basisPoints: number;
-            label?: string;
-            tokenAddress?: string;
-        }>;
+        splits?: SplitConfig[];
         chain?: string;
     }): Promise<any>;
-    updateWorkflow(workflowId: string, updates: Record<string, any>): Promise<any>;
+    /**
+     * Update a workflow. Changing `graph`, `totalPrice`, or `splits`
+     * auto-creates a new `WorkflowVersion` snapshot server-side; pass
+     * `changelog` to label it. `name`/`description` are subject to a 7-day
+     * cooldown — throws `ApinowApiError` with `status=429` and `retryAfterMs`
+     * when the cooldown is active.
+     */
+    updateWorkflow(workflowId: string, updates: {
+        name?: string;
+        description?: string;
+        status?: string;
+        totalPrice?: string;
+        splits?: SplitConfig[];
+        graph?: {
+            nodes: any[];
+            outputNode: string;
+            outputMapping?: any;
+        };
+        executionMode?: "balanced" | "optimistic" | "settle_first";
+        mermaidDiagram?: string;
+        changelog?: string;
+        [key: string]: any;
+    }): Promise<any>;
     deleteWorkflow(workflowId: string): Promise<any>;
     /**
      * List workflows you created (convenience for `listWorkflows({ creator: yourWallet })`).
@@ -161,8 +249,11 @@ export declare function createClient(config: ApinowConfig): {
      */
     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.
+     * Create a new workflow version (creator only). Defaults to setting it as
+     * default. Omit fields to inherit from current workflow. If `splits`
+     * differs from the current config, the server redeploys the 0xSplits V2
+     * contract and stores `splitterAddress` / `splitterTxHash` on the version.
+     * Splits basis points must sum to `10000`.
      */
     createWorkflowVersion(workflowId: string, updates?: {
         graph?: {
@@ -171,12 +262,7 @@ export declare function createClient(config: ApinowConfig): {
             outputMapping?: any;
         };
         totalPrice?: string;
-        splits?: Array<{
-            address: string;
-            basisPoints: number;
-            label?: string;
-            tokenAddress?: string;
-        }>;
+        splits?: SplitConfig[];
         mermaidDiagram?: string;
         executionMode?: "balanced" | "optimistic" | "settle_first";
         changelog?: string;

package/dist/index.js

@@ -2,6 +2,30 @@ 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';
+}
+/**
+ * Thrown by authed writes when the backend returns a non-2xx. Exposes status
+ * code and parsed JSON body so callers can branch on e.g. 429 cooldowns
+ * without re-parsing error text.
+ */
+export class ApinowApiError extends Error {
+    constructor(status, body) {
+        const msg = (body && typeof body === 'object' && (body.error || body.message)) ||
+            (typeof body === 'string' ? body : JSON.stringify(body));
+        super(`APINow ${status}: ${msg}`);
+        this.name = 'ApinowApiError';
+        this.status = status;
+        this.body = body;
+        if (body && typeof body === 'object') {
+            if (typeof body.retryAfterMs === 'number')
+                this.retryAfterMs = body.retryAfterMs;
+            if (typeof body.retryAfterDays === 'number')
+                this.retryAfterDays = body.retryAfterDays;
+        }
+    }
+}
 // ─── 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,31 +47,50 @@ 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's private key. Backend verifies with ethers.recoverAddress and
-     * rejects messages older than ~10 min.
-     *
-     * Exposed as a public helper so agents can sign custom write calls too.
+     * 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: ${account.address}\nissuedAt: ${issuedAt}\nnonce: ${nonce}`;
-        const signature = await account.signMessage({ message });
+        const message = `APINow auth\naddress: ${address}\nissuedAt: ${issuedAt}\nnonce: ${nonce}`;
+        const signature = await signMessage(message);
         return {
-            Authorization: `Bearer ${message}||${signature}||${account.address}`,
-            'x-wallet-address': account.address,
+            Authorization: `Bearer ${message}||${signature}||${address}`,
+            'x-wallet-address': address,
         };
     }
     /**
@@ -70,12 +113,19 @@ export function createClient(config) {
         const res = await authedFetch(url, init);
         if (!res.ok) {
             const text = await res.text();
-            throw new Error(`APINow ${res.status}: ${text}`);
+            let parsed = text;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                // leave as text
+            }
+            throw new ApinowApiError(res.status, parsed);
         }
         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.
@@ -129,6 +179,13 @@ export function createClient(config) {
             return res.json();
         },
         // ─── Endpoint CRUD ───
+        /**
+         * Create an endpoint. If `splits` are provided they must sum to exactly
+         * `10000` basis points; the server deploys a 0xSplits V2 splitter after
+         * creation and stores `splitterAddress` on the endpoint. Non-fatal if
+         * the splitter deploy fails — endpoint will exist without one and can be
+         * retried via `updateEndpoint({ splits })`.
+         */
         async createEndpoint(config) {
             return authedJson(`${baseUrl}/api/endpoints`, {
                 method: 'POST',
@@ -141,6 +198,12 @@ export function createClient(config) {
                 throw new Error(`Failed to get endpoint: ${res.status}`);
             return res.json();
         },
+        /**
+         * Update an endpoint. Changing `splits` (structurally) redeploys the
+         * splitter contract (V2 is immutable); the old address is archived on
+         * `previousSplitters[]` and the platform drains leftover USDC from it.
+         * `splits` must sum to `10000` basis points when non-empty.
+         */
         async updateEndpoint(id, updates) {
             return authedJson(`${baseUrl}/api/endpoints/${id}`, {
                 method: 'PUT',
@@ -197,6 +260,13 @@ export function createClient(config) {
                 body: JSON.stringify(config),
             });
         },
+        /**
+         * Update a workflow. Changing `graph`, `totalPrice`, or `splits`
+         * auto-creates a new `WorkflowVersion` snapshot server-side; pass
+         * `changelog` to label it. `name`/`description` are subject to a 7-day
+         * cooldown — throws `ApinowApiError` with `status=429` and `retryAfterMs`
+         * when the cooldown is active.
+         */
         async updateWorkflow(workflowId, updates) {
             return authedJson(`${baseUrl}/api/workflows/${workflowId}`, {
                 method: 'PUT',
@@ -210,7 +280,7 @@ export function createClient(config) {
          * List workflows you created (convenience for `listWorkflows({ creator: yourWallet })`).
          */
         async listMyWorkflows(opts = {}) {
-            return this.listWorkflows({ ...opts, creator: account.address });
+            return this.listWorkflows({ ...opts, creator: address });
         },
         // ─── Workflow Versions ───
         /**
@@ -232,8 +302,11 @@ export function createClient(config) {
             return res.json();
         },
         /**
-         * Create a new workflow version (creator only). Defaults to setting it as default.
-         * Omit fields to inherit from current workflow.
+         * Create a new workflow version (creator only). Defaults to setting it as
+         * default. Omit fields to inherit from current workflow. If `splits`
+         * differs from the current config, the server redeploys the 0xSplits V2
+         * contract and stores `splitterAddress` / `splitterTxHash` on the version.
+         * Splits basis points must sum to `10000`.
          */
         async createWorkflowVersion(workflowId, updates = {}) {
             return authedJson(`${baseUrl}/api/workflows/${workflowId}/versions`, {
@@ -374,7 +447,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();
@@ -409,7 +482,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}`);
@@ -419,7 +492,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`, {
@@ -440,7 +513,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.26.0",
+  "version": "0.28.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",