@ar.io/sdk 2.4.0-alpha.8 → 2.4.0

package/README.md

@@ -29,13 +29,16 @@ This is the home of [ar.io] SDK. This SDK provides functionality for interacting
     - [`getTokenSupply()`](#gettokensupply)
     - [`getBalance({ address })`](#getbalance-address-)
     - [`getBalances({ cursor, limit, sortBy, sortOrder })`](#getbalances-cursor-limit-sortby-sortorder-)
+    - [`getVault({ address, vaultId })`](#getvault-address-vaultid-)
+    - [`getVaults({ cursor, limit, sortBy, sortOrder })`](#getvaults-cursor-limit-sortby-sortorder-)
     - [`getGateway({ address })`](#getgateway-address-)
     - [`getGateways({ cursor, limit, sortBy, sortOrder })`](#getgateways-cursor-limit-sortby-sortorder-)
+    - [`buyRecord({ name, type, years, processId })`](#buyrecord-name-type-years-processid-)
     - [`getArNSRecord({ name })`](#getarnsrecord-name-)
     - [`getArNSRecords({ cursor, limit, sortBy, sortOrder })`](#getarnsrecords-cursor-limit-sortby-sortorder-)
-    - [`getAuctions({ cursor, limit, sortBy, sortOrder })`](#getauctions-cursor-limit-sortby-sortorder-)
-    - [`getAuction({ name })`](#getauction-name-)
-    - [`getAuctionPrices({ name, type, years, intervalMs })`](#getauctionprices-name-type-years-intervalms-)
+    - [`getArNSAuctions({ cursor, limit, sortBy, sortOrder })`](#getarnsauctions-cursor-limit-sortby-sortorder-)
+    - [`getArNSAuction({ name })`](#getarnsauction-name-)
+    - [`getArNSAuctionPrices({ name, type, years, intervalMs })`](#getarnsauctionprices-name-type-years-intervalms-)
     - [`getDemandFactor()`](#getdemandfactor)
     - [`getObservations({ epochIndex })`](#getobservations-epochindex-)
     - [`getDistributions({ epochIndex })`](#getdistributions-epochindex-)
@@ -395,6 +398,73 @@ const balances = await io.getBalances({
 ```
 
 </details>
+ 
+#### `getVault({ address, vaultId })`
+
+Retrieves the locked-balance user vault of the IO process by the specified wallet address and vault ID.
+
+```typescript
+const io = IO.init();
+const vault = await io.getVault({
+  address: 'QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ',
+  vaultId: 'vaultIdOne',
+});
+```
+
+<details>
+  <summary>Output</summary>
+
+```json
+{
+  "balance": 1000000,
+  "startTimestamp": 123,
+  "endTimestamp": 4567
+}
+```
+
+#### `getVaults({ cursor, limit, sortBy, sortOrder })`
+
+Retrieves all locked-balance user vaults of the IO process, paginated and sorted by the specified criteria. The `cursor` used for pagination is the last wallet address from the previous request.
+
+```typescript
+const io = IO.init();
+const vaults = await io.getVaults({
+  cursor: '0',
+  limit: 100,
+  sortBy: 'balance',
+  sortOrder: 'desc',
+});
+```
+
+<details>
+  <summary>Output</summary>
+
+```json
+{
+  "items": [
+    {
+      "address": "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ",
+      "vaultId": "vaultIdOne",
+      "balance": 1000000,
+      "startTimestamp": 123,
+      "endTimestamp": 4567
+    },
+    {
+      "address": "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ",
+      "vaultId": "vaultIdTwo",
+      "balance": 1000000,
+      "startTimestamp": 123,
+      "endTimestamp": 4567
+    }
+    // ...98 other addresses with vaults
+  ],
+  "hasMore": true,
+  "nextCursor": "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ",
+  "totalItems": 1789,
+  "sortBy": "balance",
+  "sortOrder": "desc"
+}
+```
 
 #### `getGateway({ address })`
 
@@ -508,6 +578,23 @@ Available `sortBy` options are any of the keys on the gateway object, e.g. `oper
 
 </details>
 
+#### `buyRecord({ name, type, years, processId })`
+
+Purchases a new ArNS record with the specified name, type, and duration.
+
+_Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
+
+```typescript
+const io = IO.init({ processId: IO_DEVNET_PROCESS_ID, signer });
+const record = await io.buyRecord(
+  { name: 'ardrive', type: 'lease', years: 1 },
+  {
+    // optional tags
+    tags: [{ name: 'App-Name', value: 'ArNS-App' }],
+  },
+);
+```
+
 #### `getArNSRecord({ name })`
 
 Retrieves the record info of the specified ArNS name.
@@ -606,13 +693,13 @@ Available `sortBy` options are any of the keys on the record object, e.g. `name`
 
 </details>
 
-#### `getAuctions({ cursor, limit, sortBy, sortOrder })`
+#### `getArNSAuctions({ cursor, limit, sortBy, sortOrder })`
 
 Retrieves all active auctions of the IO process, paginated and sorted by the specified criteria. The `cursor` used for pagination is the last auction name from the previous request.
 
 ```typescript
 const io = IO.init();
-const auctions = await io.getAuctions({
+const auctions = await io.getArNSAuctions({
   limit: 100,
   sortBy: 'endTimestamp',
   sortOrder: 'asc', // return the auctions ending soonest first
@@ -649,13 +736,13 @@ const auctions = await io.getAuctions({
 
 </details>
 
-#### `getAuction({ name })`
+#### `getArNSAuction({ name })`
 
 Retrieves the auction data for the specified auction name.
 
 ```typescript
 const io = IO.init();
-const auction = await io.getAuction({ name: 'permalink' });
+const auction = await io.getArNSAuction({ name: 'permalink' });
 ```
 
 <details>
@@ -680,13 +767,13 @@ const auction = await io.getAuction({ name: 'permalink' });
 
 </details>
 
-#### `getAuctionPrices({ name, type, years, intervalMs })`
+#### `getArNSAuctionPrices({ name, type, years, intervalMs })`
 
 Retrieves the auction price curve of the specified auction name for the specified type, duration, and interval. The `intervalMs` is the number of milliseconds between price points on the curve. The default interval is 15 minutes.
 
 ```typescript
 const io = IO.init();
-const priceCurve = await io.getAuctionPrices({
+const priceCurve = await io.getArNSAuctionPrices({
   name: 'permalink',
   type: 'lease',
   years: 1,
@@ -1283,7 +1370,7 @@ _Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
 ```typescript
 const io = IO.init({ signer: new ArweaveSigner(jwk) });
 
-const auction = await io.getAuction({ name: 'permalink' });
+const auction = await io.getArNSAuction({ name: 'permalink' });
 
 // check the current price is under some threshold
 if (auction && auction.currentPrice <= new IOToken(20_000).toMIO().valueOf()) {
@@ -1758,6 +1845,7 @@ For more information on how to use AO and AO Connect within this library, please
 - `yarn example:web` - opens up the example web page
 - `yarn example:cjs` - runs example CJS node script
 - `yarn example:esm` - runs example ESM node script
+- `yarn example:vite` - runs example Vite web page
 
 ### Linting & Formatting