apinow-sdk 0.13.0 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +118 -76
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,107 +1,149 @@
1
- # ApiNow SDK
1
+ # apinow-sdk
2
2
 
3
- A TypeScript SDK for interacting with ApiNow endpoints, supporting Ethereum and Base chains. This SDK simplifies payments by automatically handling `402 Payment Required` responses, including on-the-fly token swaps.
3
+ Pay-per-call API SDK for [APINow.fun](https://apinow.fun) — wraps [x402](https://www.x402.org/) so you don't have to.
4
4
 
5
- ## Features
6
-
7
- - **Automatic x402 Payments**: Intercepts `402` responses to handle payment flows automatically.
8
- - **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.
9
- - **Flexible Pricing**: Supports endpoints that require a fixed token amount or a USD equivalent.
10
- - **Endpoint Discovery**: Includes a `search` method to find endpoints semantically.
11
- - **Configurable Payment**: Prioritize which tokens you prefer to pay with.
12
- - **Multi-chain support**: Works with Ethereum and Base.
13
- - **Node.js Environment**: Designed to work in a Node.js environment.
14
-
15
- ## Installation
5
+ ## Install
16
6
 
17
7
  ```bash
18
8
  npm install apinow-sdk
19
- # or
20
- yarn add apinow-sdk
21
9
  ```
22
10
 
23
- ## Quick Example
11
+ ## Quick Start
12
+
13
+ ```typescript
14
+ import { createClient } from 'apinow-sdk';
15
+
16
+ const apinow = createClient({
17
+ privateKey: process.env.PRIVATE_KEY as `0x${string}`,
18
+ });
19
+
20
+ const result = await apinow.call('/api/endpoints/apinowfun/translate-TRANSLATE', {
21
+ method: 'POST',
22
+ body: { text: 'Hello world', selectedLanguage: 'es' },
23
+ });
24
+
25
+ console.log(result);
26
+ ```
27
+
28
+ That's it. If the endpoint requires payment, the SDK handles the full [x402 payment flow](https://www.x402.org/) automatically — no manual token handling, no extra steps.
24
29
 
25
- 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.
30
+ ## How It Works
31
+
32
+ 1. You call an APINow endpoint via `apinow.call()`
33
+ 2. If the server responds with `402 Payment Required`, the underlying `@x402/fetch` layer intercepts it
34
+ 3. Payment is signed and submitted using your wallet
35
+ 4. The original request is retried with proof of payment
36
+ 5. You get the API response back
37
+
38
+ ## API
39
+
40
+ ### `createClient(config)`
41
+
42
+ Creates an SDK client instance.
26
43
 
27
44
  ```typescript
28
- import apiNow from 'apinow-sdk';
29
-
30
- // Your private key, securely stored (e.g., in an environment variable).
31
- const YOUR_WALLET_PRIVATE_KEY = process.env.USER_PRIVATE_KEY;
32
-
33
- async function main() {
34
- try {
35
- // The `execute` method handles everything automatically.
36
- // If the API requires a payment (402), the SDK will find the best
37
- // token you hold, swap if necessary, send the payment, and retry
38
- // the original request with proof of payment.
39
- const response = await apiNow.execute(
40
- 'https://apinow.fun/api/endpoints/apinowfun/translate-TRANSLATE',
41
- YOUR_WALLET_PRIVATE_KEY,
42
- { // Optional: request options
43
- method: 'POST',
44
- data: {
45
- text: 'Hello world',
46
- selectedLanguage: 'es'
47
- }
48
- }
49
- );
50
-
51
- console.log('API Response:', response);
52
- } catch (error) {
53
- console.error('Operation failed:', error);
54
- }
55
- }
45
+ import { createClient } from 'apinow-sdk';
46
+ // or
47
+ import createClient from 'apinow-sdk';
48
+
49
+ const apinow = createClient({
50
+ privateKey: '0x...', // required — EVM private key
51
+ baseUrl: 'https://apinow.fun', // optional — defaults to https://apinow.fun
52
+ });
53
+ ```
54
+
55
+ Returns an object with:
56
+
57
+ | Property | Description |
58
+ |----------|-------------|
59
+ | `wallet` | Your wallet address (derived from private key) |
60
+ | `call()` | Call any APINow endpoint with automatic x402 payment |
61
+ | `search()` | Semantic search across all APINow endpoints |
62
+ | `info()` | Get public endpoint info (free, no payment) |
63
+ | `fetch` | The underlying x402-wrapped `fetch` for advanced use |
64
+
65
+ ---
56
66
 
57
- main();
67
+ ### `apinow.call(endpoint, opts?)`
68
+
69
+ Call any APINow endpoint. Handles x402 payment automatically.
70
+
71
+ ```typescript
72
+ const data = await apinow.call('/api/endpoints/apinowfun/translate-TRANSLATE', {
73
+ method: 'POST',
74
+ body: { text: 'Hello world', selectedLanguage: 'es' },
75
+ });
58
76
  ```
59
77
 
60
- For a complete, runnable example, see [`example.js`](./example.js).
78
+ **Parameters:**
79
+
80
+ | Param | Type | Default | Description |
81
+ |-------|------|---------|-------------|
82
+ | `endpoint` | `string` | — | Full URL or path (paths are resolved against `baseUrl`) |
83
+ | `opts.method` | `'GET' \| 'POST' \| 'PUT' \| 'DELETE'` | `'POST'` | HTTP method |
84
+ | `opts.body` | `Record<string, any>` | — | Request body (ignored for GET) |
85
+ | `opts.headers` | `Record<string, string>` | — | Additional headers |
86
+
87
+ **Returns:** `Promise<any>` — parsed JSON response.
61
88
 
62
- ## How It Works: Automatic Payments
89
+ ---
90
+
91
+ ### `apinow.search(query, limit?)`
92
+
93
+ Semantic search across all APINow endpoints.
94
+
95
+ ```typescript
96
+ const results = await apinow.search('translate text', 5);
97
+ ```
63
98
 
64
- 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:
99
+ | Param | Type | Default | Description |
100
+ |-------|------|---------|-------------|
101
+ | `query` | `string` | — | Search query |
102
+ | `limit` | `number` | `10` | Max results |
65
103
 
66
- 1. **Parses Payment Options**: The `402` response contains a list of accepted payment options.
67
- 2. **Checks Balances**: It checks your wallet balance for each of the accepted payment tokens.
68
- 3. **Prioritizes Payment**: It attempts to pay using your tokens in a preferred order (default: `['USDC', 'WETH', 'ETH']`).
69
- 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.
70
- 5. **Pays and Retries**: Once the payment transaction is sent, the SDK automatically retries the original API request, now with proof of payment.
104
+ ---
71
105
 
72
- ## API Reference
106
+ ### `apinow.info(namespace, endpointName)`
73
107
 
74
- ### `execute(endpoint, privateKey, opts?, paymentConfig?)`
75
- Handles a request and its potential payment in a single, automatic call. This is the recommended method.
108
+ Get public endpoint details. Free — no payment required.
76
109
 
77
- ### `search(params, privateKey, paymentConfig?)`
78
- Performs a semantic search for endpoints.
110
+ ```typescript
111
+ const details = await apinow.info('apinowfun', 'translate-TRANSLATE');
112
+ ```
79
113
 
80
- ### `info(endpointUrl)`
81
- Retrieves public, detailed information about an endpoint.
114
+ ---
82
115
 
83
- ## Default RPC URLs
116
+ ### `apinow.fetch`
84
117
 
85
- - **Ethereum:** `https://rpc.ankr.com/eth`
86
- - **Base:** `https://mainnet.base.org`
118
+ The raw x402-wrapped `fetch` function, if you need full control over requests.
87
119
 
88
- ## Error Handling
120
+ ```typescript
121
+ const res = await apinow.fetch('https://apinow.fun/api/endpoints/...', {
122
+ method: 'POST',
123
+ headers: { 'Content-Type': 'application/json' },
124
+ body: JSON.stringify({ key: 'value' }),
125
+ });
126
+ ```
89
127
 
90
- The SDK throws descriptive errors for:
91
- - Invalid endpoint URLs or configurations.
92
- - RPC communication errors.
93
- - Transaction signing or sending failures.
94
- - Insufficient funds or failure to find a valid swap.
95
- - Failures during API response fetching.
128
+ ## Types
96
129
 
97
- Wrap calls in `try...catch` blocks for robust error handling.
130
+ ```typescript
131
+ interface ApinowConfig {
132
+ privateKey: `0x${string}`;
133
+ baseUrl?: string;
134
+ }
98
135
 
99
- ## Compatibility
136
+ interface CallOptions {
137
+ method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
138
+ body?: Record<string, any>;
139
+ headers?: Record<string, string>;
140
+ }
141
+ ```
100
142
 
101
- This SDK uses `node-fetch`, making it compatible with:
102
- - Node.js (v18+ recommended)
143
+ ## Requirements
103
144
 
104
- It is NOT directly compatible with browsers or edge environments that do not provide a Node.js-compatible `fetch` API.
145
+ - Node.js v18+ (uses native `fetch`)
146
+ - An EVM wallet with funds on Base for paid endpoints
105
147
 
106
148
  ## License
107
149
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "apinow-sdk",
3
- "version": "0.13.0",
3
+ "version": "0.14.0",
4
4
  "description": "Pay-per-call API SDK for APINow.fun — wraps x402 so you don't have to",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",