apinow-sdk 0.12.5 → 0.12.6

package/README.md

@@ -7,6 +7,7 @@ A TypeScript SDK for interacting with ApiNow endpoints, supporting Ethereum and
 - **Automatic x402 Payments**: Intercepts `402` responses to handle payment flows automatically.
 - **On-the-fly Token Swaps**: If you don't have the required payment token, the SDK can swap a common asset (like ETH, WETH, or USDC) to make the payment, powered by 0x.
 - **Flexible Pricing**: Supports endpoints that require a fixed token amount or a USD equivalent.
+- **Endpoint Discovery**: Includes a `search` method to find endpoints semantically.
 - **Configurable Payment**: Prioritize which tokens you prefer to pay with.
 - **Multi-chain support**: Works with Ethereum and Base.
 - **Node.js Environment**: Designed to work in a Node.js environment.
@@ -19,33 +20,31 @@ npm install apinow-sdk
 yarn add apinow-sdk
 ```
 
-## Usage
+## Quick Example
 
 The primary way to use the SDK is with the `execute` method. It's a single call that handles all the complexity of API payments for you.
 
 ```typescript
 import apiNow from 'apinow-sdk';
 
-// The API endpoint you want to interact with.
-const ENDPOINT_URL = 'https://apinow.fun/api/endpoints/your-endpoint';
-
 // Your private key, securely stored (e.g., in an environment variable).
-const YOUR_WALLET_PRIVATE_KEY = '0x...'; 
+const YOUR_WALLET_PRIVATE_KEY = process.env.USER_PRIVATE_KEY; 
 
 async function main() {
   try {
     // The `execute` method handles everything automatically.
-    // If the API requires a payment (402), the SDK will:
-    // 1. Find the best token you hold to pay with.
-    // 2. If needed, swap a common asset (like ETH or USDC) to the required token.
-    // 3. Send the payment transaction.
-    // 4. Retry the original request with proof of payment.
+    // If the API requires a payment (402), the SDK will find the best
+    // token you hold, swap if necessary, send the payment, and retry
+    // the original request with proof of payment.
     const response = await apiNow.execute(
-      ENDPOINT_URL,
+      'https://apinow.fun/api/endpoints/apinowfun/translate-TRANSLATE',
       YOUR_WALLET_PRIVATE_KEY,
       { // Optional: request options
         method: 'POST',
-        data: { query: 'your-data' }
+        data: { 
+            text: 'Hello world',
+            selectedLanguage: 'es'
+        }
       }
     );
 
@@ -58,100 +57,28 @@ async function main() {
 main();
 ```
 
+For a complete, runnable example, see [`example.js`](./example.js).
+
 ## How It Works: Automatic Payments
 
 When you call `execute`, the SDK makes a request to the endpoint. If the server responds with a `402 Payment Required` status, the SDK automatically performs the following steps:
 
-1.  **Parses Payment Options**: The `402` response contains a list of accepted payment options. This can be a single token (fixed price) or multiple tokens (USD equivalent price, e.g., "$5 of USDC" or "$5 of ETH").
+1.  **Parses Payment Options**: The `402` response contains a list of accepted payment options.
 2.  **Checks Balances**: It checks your wallet balance for each of the accepted payment tokens.
 3.  **Prioritizes Payment**: It attempts to pay using your tokens in a preferred order (default: `['USDC', 'WETH', 'ETH']`).
-4.  **Swaps if Needed**: If you don't have any of the *required* tokens, the SDK will try to swap one of your preferred assets for the required one. For example, it can swap your USDC to pay with a different required token.
+4.  **Swaps if Needed**: If you don't have any of the *required* tokens, the SDK will try to swap one of your preferred assets for the required one.
 5.  **Pays and Retries**: Once the payment transaction is sent, the SDK automatically retries the original API request, now with proof of payment.
 
-## Configuration
-
-You can customize the behavior of the `execute` method with the `opts` and `paymentConfig` parameters.
-
-### Request Options (`opts`)
-
-Passed as the third argument to `execute`. This corresponds to `TxResponseOptions`.
-
--   `method`: The HTTP method for your request (e.g., `'GET'`, `'POST'`). Defaults to `'GET'`.
--   `data`: The payload for your request. For `POST` requests, this is the JSON body. For `GET`, it's converted to query parameters.
-
-### Payment Configuration (`paymentConfig`)
-
-Passed as the fourth argument to `execute`. This corresponds to `X402PaymentConfig`.
-
--   `preferredTokens`: An array of token symbols (e.g., `['USDC', 'WETH']`) that you prefer to pay with. The SDK will check your balance of these tokens first.
-
-```typescript
-await apiNow.execute(
-  ENDPOINT_URL,
-  YOUR_WALLET_PRIVATE_KEY,
-  { method: 'POST', data: { /* ... */ } }, // opts
-  { preferredTokens: ['DAI', 'USDC'] }   // paymentConfig
-);
-```
-
-## Legacy Flow (Backward Compatibility)
-
-For backward compatibility, the `infoBuyResponse` method is still available. It performs a less sophisticated multi-step payment process.
-
-```typescript
-const response = await apiNow.infoBuyResponse(
-  ENDPOINT_URL,
-  YOUR_WALLET_PRIVATE_KEY
-);
-```
-
 ## API Reference
 
 ### `execute(endpoint, privateKey, opts?, paymentConfig?)`
 Handles a request and its potential payment in a single, automatic call. This is the recommended method.
 
-### `infoBuyResponse(endpoint, privateKey, rpcUrl?, opts?)`
-(Legacy) Combines `info`, `buy`, and `txResponse` into a single call.
-
-### `info(endpoint)`
-(Legacy) Gets payment requirement information from an endpoint.
-
-### `buy(walletAddress, amount, privateKey, chain, ...)`
-(Legacy) Sends a payment transaction.
-
-### `txResponse(endpoint, txHash, opts?)`
-(Legacy) Fetches the API response after a payment has been made manually.
+### `search(params, privateKey, paymentConfig?)`
+Performs a semantic search for endpoints.
 
-## Types
-
-```typescript
-// Response from a 402 error
-interface X402PaymentInfo {
-  challenge: string;
-  chain: 'eth' | 'base';
-  recipientAddress: string;
-  options: X402PaymentOption[];
-}
-
-// A single way to pay
-interface X402PaymentOption {
-  tokenAddress: string;
-  symbol: string;
-  amount: string;
-  decimals: number;
-}
-
-// Configuration for payments
-interface X402PaymentConfig {
-  preferredTokens?: string[];
-}
-
-// Options for the API request itself
-interface TxResponseOptions {
-  method?: string; 
-  data?: any;      
-}
-```
+### `info(endpointUrl)`
+Retrieves public, detailed information about an endpoint.
 
 ## Default RPC URLs
 
@@ -179,47 +106,3 @@ It is NOT directly compatible with browsers or edge environments that do not pro
 ## License
 
 MIT
-
-## Examples
-
-This project includes a test server and a test runner to demonstrate various payment scenarios.
-
-1.  **Create a `.env` file** in the root of the project and add your wallet's private key:
-    ```
-    PRIVATE_KEY=your_private_key_here
-    ```
-
-2.  **Install dependencies:**
-    ```bash
-    npm install
-    ```
-
-3.  **Start the test server:**
-    The test server simulates an API that requires different types of payments.
-    ```bash
-    node test/test-server.js
-    ```
-
-4.  **Run the test runner:**
-    In a separate terminal, run the test runner to execute a series of transactions against the test server.
-    ```bash
-    node test/test-runner.js
-    ```
-
-This will demonstrate:
-- Paying with USDC
-- Paying with a custom ERC20 token
-- Paying with a token priced in USDC
-- Fallback token payments
-- Handling various error conditions
-
-## Local Development
-
-1. **Build the project:**
-   ```bash
-   npm run build
-   ```
-
-This will compile the TypeScript source files into JavaScript in the `dist` directory.
-
-## Contributing

package/dist/index.d.ts

@@ -4,13 +4,35 @@ interface TxResponseOptions {
     data?: any;
     signature?: string;
 }
-interface InfoResponse {
-    requiredAmount: string;
+interface PaymentOption {
+    tokenAddress: string;
+    symbol: string;
+    amount?: string;
+    usdAmount?: string;
+    decimals: number;
+}
+interface EndpointInfo {
+    namespace: string;
+    endpointName: string;
+    description: string;
     walletAddress: string;
+    paymentOptions: PaymentOption[];
     httpMethod: string;
-    tokenAddress?: string;
-    chain: 'eth' | 'base';
-    decimals?: number;
+    querySchema?: any;
+    docsUrl?: string;
+    status: string;
+    chain: 'eth' | 'sol' | 'base';
+    url: string;
+    lastTx?: {
+        txHash: string;
+        chain: 'eth' | 'sol';
+        timestamp: string;
+    };
+}
+interface SearchParams {
+    query: string;
+    limit?: number;
+    minScore?: number;
 }
 interface X402PaymentOption {
     tokenAddress: string;
@@ -36,16 +58,14 @@ interface X402PaymentConfig {
 declare function get0xSwapQuote(buyToken: string, sellToken: string, buyAmount: bigint, buyTokenDecimals: number, takerAddress: string, chain: 'eth' | 'base', slippagePercentage?: string): Promise<any>;
 declare class ApiNow {
     private handlers;
-    info(endpoint: string): Promise<InfoResponse>;
+    info(endpointUrl: string): Promise<EndpointInfo>;
+    search(params: SearchParams, userWalletPrivateKey: string, paymentConfig?: X402PaymentConfig): Promise<any>;
     buy(walletAddress: string, amount: bigint, userWalletPrivateKey: string, chain: 'eth' | 'base', rpcUrl?: string, tokenAddress?: string, fastMode?: boolean): Promise<string>;
     execute(endpoint: string, userWalletPrivateKey: string, opts?: TxResponseOptions, paymentConfig?: X402PaymentConfig): Promise<any>;
     approve(wallet: Wallet, tokenAddress: string, spenderAddress: string, amount: bigint): Promise<string>;
     txResponse(endpoint: string, txHash: string, opts?: TxResponseOptions): Promise<any>;
-    infoBuyResponse(endpoint: string, userWalletPrivateKey: string, rpcUrl?: string, opts?: TxResponseOptions & {
-        fastMode?: boolean;
-    }): Promise<any>;
 }
 declare const apiNow: ApiNow;
 export default apiNow;
 export { get0xSwapQuote };
-export type { InfoResponse, TxResponseOptions, X402PaymentInfo, X402PaymentOption, X402PaymentConfig };
+export type { TxResponseOptions, X402PaymentInfo, X402PaymentOption, X402PaymentConfig, EndpointInfo, SearchParams, PaymentOption };

package/dist/index.js

@@ -519,18 +519,42 @@ class ApiNow {
             base: new EthereumHandler()
         };
     }
-    async info(endpoint) {
-        if (!endpoint || typeof endpoint !== 'string') {
-            throw new Error('Invalid endpoint URL');
-        }
+    async info(endpointUrl) {
+        if (!endpointUrl || typeof endpointUrl !== 'string') {
+            throw new Error('Invalid endpoint URL provided.');
+        }
+        // Ensure the URL doesn't already end in /details before appending
+        const detailsUrl = endpointUrl.endsWith('/details')
+            ? endpointUrl
+            : `${endpointUrl}/details`;
+        console.log(`[sdk] Fetching public info from: ${detailsUrl}`);
         try {
-            return await fetchJson(endpoint);
+            // Using a simple fetch as this is a public, non-paying endpoint
+            const response = await fetch(detailsUrl);
+            if (!response.ok) {
+                const errorBody = await response.text();
+                throw new Error(`Failed to fetch endpoint info (${response.status}): ${errorBody}`);
+            }
+            return await response.json();
         }
         catch (error) {
-            console.error(`Failed to fetch info from ${endpoint}:`, error);
-            throw new Error(`Could not get endpoint info: ${error instanceof Error ? error.message : String(error)}`);
+            console.error(`[sdk] Error in info():`, error);
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Could not get endpoint info: ${message}`);
         }
     }
+    async search(params, userWalletPrivateKey, paymentConfig = {}) {
+        const searchEndpoint = 'https://apinow.fun/api/endpoints/apinowfun/endpoint-search';
+        console.log(`[sdk] Performing semantic search with query: "${params.query}"`);
+        if (!params.query || typeof params.query !== 'string' || params.query.trim() === '') {
+            throw new Error('A non-empty search query string is required.');
+        }
+        // Reuse the existing execute method to handle the x402 payment flow
+        return this.execute(searchEndpoint, userWalletPrivateKey, {
+            method: 'POST',
+            data: params, // The search parameters become the body of the POST request
+        }, paymentConfig);
+    }
     async buy(walletAddress, amount, userWalletPrivateKey, chain, rpcUrl, tokenAddress, fastMode) {
         const handler = this.handlers[chain];
         if (!handler) {
@@ -643,48 +667,6 @@ class ApiNow {
             throw new Error(`Could not get transaction response: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
-    async infoBuyResponse(endpoint, userWalletPrivateKey, rpcUrl, opts = {}) {
-        console.error(`Starting infoBuyResponse for endpoint: ${endpoint}`);
-        const info = await this.info(endpoint);
-        console.error("Received info:", info);
-        const { requiredAmount, walletAddress, chain, tokenAddress, decimals } = info;
-        if (!chain || !this.handlers[chain]) {
-            throw new Error(`Unsupported chain specified by endpoint: ${chain}`);
-        }
-        let amountBigInt;
-        try {
-            // Use info.decimals if available, otherwise default to 18 (for ETH)
-            const parseDecimals = (tokenAddress && decimals !== undefined) ? decimals : 18;
-            amountBigInt = parseUnits(requiredAmount, parseDecimals);
-            if (amountBigInt <= 0n) {
-                throw new Error('Required amount must be positive.');
-            }
-        }
-        catch (e) {
-            throw new Error(`Invalid requiredAmount format or value: ${requiredAmount}. Could not parse with ${(tokenAddress && decimals !== undefined) ? decimals : 18} decimals.`);
-        }
-        console.error(`Attempting payment: Chain=${chain}, To=${walletAddress}, Amount=${amountBigInt.toString()}, Token=${tokenAddress || 'Native'}`);
-        const txHash = await this.buy(walletAddress, amountBigInt, userWalletPrivateKey, chain, rpcUrl, tokenAddress, opts.fastMode);
-        console.error(`Transaction sent: ${txHash}`);
-        const wallet = new Wallet(userWalletPrivateKey);
-        const signature = await wallet.signMessage(txHash);
-        console.error(`Generated signature for txHash ${txHash}: ${signature}`);
-        if (!opts.fastMode) {
-            await new Promise(resolve => setTimeout(resolve, 3000));
-        }
-        else {
-            await new Promise(resolve => setTimeout(resolve, 500));
-        }
-        console.error(`Fetching response for tx: ${txHash}`);
-        // Create specific options for txResponse
-        const txResponseOpts = {
-            method: info.httpMethod || 'POST', // Use the method from info, default to POST
-            data: opts.data, // Pass the original data payload intended for the API
-            signature: signature
-        };
-        // Call txResponse with the tailored options
-        return this.txResponse(endpoint, txHash, txResponseOpts);
-    }
 }
 const apiNow = new ApiNow();
 export default apiNow;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apinow-sdk",
-  "version": "0.12.5",
+  "version": "0.12.6",
   "description": "ApiNow SDK · The endpoint vending machine",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",