@ardrive/turbo-sdk 1.23.4 → 1.24.0-alpha.1

package/README.md

@@ -13,79 +13,17 @@ Welcome to the `@ardrive/turbo-sdk`! This SDK provides functionality for interac
 - [Quick Start](#quick-start)
 - [Usage](#usage)
   - [Web](#web)
-    - [Bundlers (Webpack, Rollup, ESbuild, etc.)](#bundlers-webpack-rollup-esbuild-etc)
-    - [Browser](#browser)
   - [NodeJS](#nodejs)
-    - [CommonJS](#commonjs)
-    - [ESM](#esm)
   - [Typescript](#typescript)
   - [Examples](#examples)
 - [Logging](#logging)
 - [APIs](#apis)
   - [TurboFactory](#turbofactory)
-    - [`unauthenticated()`](#unauthenticated)
-    - [`authenticated()`](#authenticated)
-      - [Arweave JWK](#arweave-jwk)
-      - [ArweaveSigner](#arweavesigner)
-      - [ArconnectSigner](#arconnectsigner)
-      - [EthereumSigner](#ethereumsigner)
-      - [Ethereum Private Key](#ethereum-private-key)
-      - [POL (MATIC) Private Key](#pol-matic-private-key)
-      - [HexSolanaSigner](#hexsolanasigner)
-      - [Solana Secret Key](#solana-secret-key)
-      - [KYVE Private Key](#kyve-private-key)
-      - [KYVE Mnemonic](#kyve-mnemonic)
   - [TurboUnauthenticatedClient](#turbounauthenticatedclient)
-    - [`getSupportedCurrencies()`](#getsupportedcurrencies)
-    - [`getSupportedCountries()`](#getsupportedcountries)
-    - [`getFiatToAR({ currency })`](#getfiattoar-currency-)
-    - [`getFiatRates()`](#getfiatrates)
-    - [`getWincForFiat({ amount })`](#getwincforfiat-amount-)
-    - [`getWincForToken({ tokenAmount })`](#getwincfortoken-tokenamount-)
-    - [`getTokenPriceForBytes({ byteCount })`](#gettokenpriceforbytes-bytecount-)
-    - [`getUploadCosts({ bytes })`](#getuploadcosts-bytes-)
-    - [`uploadSignedDataItem({ dataItemStreamFactory, dataItemSizeFactory, signal })`](#uploadsigneddataitem-dataitemstreamfactory-dataitemsizefactory-signal-)
-    - [`createCheckoutSession({ amount, owner })`](#createcheckoutsession-amount-owner-)
-      - [Arweave (AR) Fiat Top Up](#arweave-ar-fiat-top-up)
-      - [Ethereum (ETH) Fiat Top Up](#ethereum-eth-fiat-top-up)
-      - [Solana (SOL) Fiat Top Up](#solana-sol-fiat-top-up)
-      - [Polygon (POL / MATIC) Fiat Top Up](#polygon-pol--matic-fiat-top-up)
-      - [KYVE Fiat Top Up](#kyve-fiat-top-up)
-    - [`submitFundTransaction({ txId })`](#submitfundtransaction-txid-)
   - [TurboAuthenticatedClient](#turboauthenticatedclient)
-    - [`getBalance()`](#getbalance)
-    - [`signer.getNativeAddress()`](#signergetnativeaddress)
-    - [`getWincForFiat({ amount, promoCodes })`](#getwincforfiat-amount-promocodes-)
-    - [`createCheckoutSession({ amount, owner, promoCodes })`](#createcheckoutsession-amount-owner-promocodes-)
-    - [`uploadFile({ fileStreamFactory, fileSizeFactory, signal, dataItemOpts })`](#uploadfile-filestreamfactory-filesizefactory-signal-dataitemopts-)
-    - [`uploadFolder({ folderPath, files, dataItemOpts, signal, maxConcurrentUploads, throwOnFailure, manifestOptions })`](#uploadfolder-folderpath-files-dataitemopts-signal-maxconcurrentuploads-throwonfailure-manifestoptions-)
-      - [NodeJS Upload Folder](#nodejs-upload-folder)
-      - [Browser Upload Folder](#browser-upload-folder)
-    - [`topUpWithTokens({ tokenAmount, feeMultiplier })`](#topupwithtokens-tokenamount-feemultiplier-)
-      - [Arweave (AR) Crypto Top Up](#arweave-ar-crypto-top-up)
-      - [Ethereum (ETH) Crypto Top Up](#ethereum-eth-crypto-top-up)
-      - [Polygon (POL / MATIC) Crypto Top Up](#polygon-pol--matic-crypto-top-up)
-      - [Eth on Base Network Crypto Top Up](#eth-on-base-network-crypto-top-up)
-      - [Solana (SOL) Crypto Top Up](#solana-sol-crypto-top-up)
-      - [KYVE Crypto Top Up](#kyve-crypto-top-up)
-    - [`shareCredits({ approvedAddress, approvedWincAmount, expiresBySeconds })`](#sharecredits-approvedaddress-approvedwincamount-expiresbyseconds-)
-    - [`revokeCredits({ approvedAddress })`](#revokecredits-approvedaddress-)
-    - [`getCreditShareApprovals({ userAddress })`](#getcreditshareapprovals-useraddress-)
 - [CLI](#cli)
-  - [Install CLI](#install-cli)
-  - [CLI Usage](#cli-usage)
-    - [Options](#options)
-    - [Commands](#commands)
-      - [`balance`](#balance)
-      - [`top-up`](#top-up)
-      - [`crypto-fund`](#crypto-fund)
-      - [`upload-folder`](#upload-folder)
-      - [`upload-file`](#upload-file)
-      - [`price`](#price)
-      - [`token-price`](#token-price)
-      - [`share-credits`](#share-credits)
-      - [`revoke-credits`](#revoke-credits)
-      - [`list-shares`](#list-shares)
+  - [Installation](#installation-1)
+  - [Usage](#usage-1)
 - [Turbo Credit Sharing](#turbo-credit-sharing)
 - [Developers](#developers)
   - [Requirements](#requirements)
@@ -111,55 +49,74 @@ yarn add @ardrive/turbo-sdk
 ## Quick Start
 
 ```typescript
-import { TurboFactory, ArweaveSigner } from '@ardrive/turbo-sdk';
-
-// load your JWK directly to authenticate
-const jwk = fs.readFileSync('./my-jwk.json');
-const address = arweave.wallets.jwkToAddress(jwk);
-const turbo = TurboFactory.authenticated({ privateKey: jwk });
-
-// or provide your own signer
-const signer = new ArweaveSigner(jwk);
-const turbo = TurboFactory.authenticated({ signer });
-
-// get the wallet balance
-const { winc: balance } = await turbo.getBalance();
-
-// prep file for upload
-const filePath = path.join(__dirname, './my-image.png');
-const fileSize = fs.statSync(filePath).size;
-
-// get the cost of uploading the file
-const [{ winc: fileSizeCost }] = await turbo.getUploadCosts({
-  bytes: [fileSize],
-});
-
-// check if balance greater than upload cost
-if (balance < fileSizeCost) {
-  const { url } = await turbo.createCheckoutSession({
-    amount: fileSizeCost,
-    owner: address,
-    // add a promo code if you have one
+import { ArweaveSigner, TurboFactory } from '@ardrive/turbo-sdk';
+import Arweave from 'arweave';
+import fs from 'fs';
+import open from 'open';
+import path from 'path';
+
+async function uploadWithTurbo() {
+  // load your JWK directly to authenticate
+  const arweave = Arweave({});
+  const jwk = JSON.parse(fs.readFileSync('./my-jwk.json', 'utf-8'));
+  const address = await arweave.wallets.jwkToAddress(jwk);
+  const turbo = TurboFactory.authenticated({ privateKey: jwk });
+
+  // or provide your own signer
+  // const signer = new ArweaveSigner(jwk);
+  // const turbo = TurboFactory.authenticated({ signer });
+
+  // get the wallet balance
+  const { winc: balance } = await turbo.getBalance();
+
+  // prep file for upload
+  const filePath = path.join(__dirname, './my-image.png');
+  const fileSize = fs.statSync(filePath).size;
+
+  // get the cost of uploading the file
+  const [{ winc: fileSizeCost }] = await turbo.getUploadCosts({
+    bytes: [fileSize],
   });
-  // open the URL to top-up, continue when done
-  open(url);
-  return;
-}
 
-// upload the file
-try {
-  const { id, owner, dataCaches, fastFinalityIndexes } = await turbo.uploadFile(() => {
-    fileStreamFactory => () => fs.createReadStream(filePath),
-    fileSizeFactory => () => fileSize,
-  });
-  // upload complete!
-  console.log('Successfully upload data item!', { id, owner, dataCaches, fastFinalityIndexes });
-} catch (error) {
-  // upload failed
-  console.error('Failed to upload data item!', error);
-} finally {
-  const { winc: newBalance } = await turbo.getBalance();
-  console.log('New balance:', newBalance);
+  // check if balance greater than upload cost, and if in browser
+  if (balance < fileSizeCost && window !== undefined) {
+    const { url } = await turbo.createCheckoutSession({
+      amount: fileSizeCost,
+      owner: address,
+      // add a promo code if you have one
+    });
+
+    // open the URL to top-up if in browser
+    window.open(url, '_blank');
+  } else {
+    // otherwise, print the URL to the console
+    console.log('Please top up your balance via the CLI before uploading', {
+      balance,
+      fileSizeCost,
+    });
+  }
+
+  // upload the file
+  try {
+    const { id, owner, dataCaches, fastFinalityIndexes } =
+      await turbo.uploadFile({
+        fileStreamFactory: () => fs.createReadStream(filePath),
+        fileSizeFactory: () => fileSize,
+      });
+    // upload complete!
+    console.log('Successfully upload data item!', {
+      id,
+      owner,
+      dataCaches,
+      fastFinalityIndexes,
+    });
+  } catch (error) {
+    // upload failed
+    console.error('Failed to upload data item!', error);
+  } finally {
+    const { winc: newBalance } = await turbo.getBalance();
+    console.log('New balance:', newBalance);
+  }
 }
 ```
 
@@ -169,24 +126,13 @@ The SDK is provided in both CommonJS and ESM formats, and it's compatible with b
 
 ### Web
 
-#### Bundlers (Webpack, Rollup, ESbuild, etc.)
-
-CommonJS:
-
-```javascript
-import { TurboFactory } from '@ardrive/turbo-sdk';
-
-const turbo = TurboFactory.unauthenticated();
-const rates = await turbo.getFiatRates();
-```
-
 > [!WARNING]
 > Polyfills are not provided by default for bundled web projects (Vite, ESBuild, Webpack, Rollup, etc.) . Depending on your apps bundler configuration and plugins, you will need to provide polyfills for various imports including `crypto`, `process`, `fs` and `buffer`. Refer to your bundler's documentation for how to provide the necessary polyfills.
 
-ESM:
+#### Bundlers (Webpack, Rollup, ESbuild, etc.)
 
-```javascript
-import { TurboFactory } from '@ardrive/turbo-sdk/<node/web>';
+```typescript
+import { TurboFactory } from '@ardrive/turbo-sdk/web';
 
 const turbo = TurboFactory.unauthenticated();
 const rates = await turbo.getFiatRates();
@@ -207,11 +153,25 @@ const rates = await turbo.getFiatRates();
 
 #### CommonJS
 
-Example available in the [examples/typescript/cjs].
+Full example available in the [examples/typescript/cjs].
+
+```typescript
+import { TurboFactory } from '@ardrive/turbo-sdk';
+
+const turbo = TurboFactory.unauthenticated();
+const rates = await turbo.getFiatRates();
+```
 
 #### ESM
 
-Example available in the [examples/typescript/esm].
+Full example available in the [examples/typescript/esm].
+
+```typescript
+import { TurboFactory } from '@ardrive/turbo-sdk/node';
+
+const turbo = TurboFactory.unauthenticated();
+const rates = await turbo.getFiatRates();
+```
 
 ### Typescript
 
@@ -444,21 +404,12 @@ const { url, winc, paymentAmount, quotedPaymentAmount, adjustments } =
   });
 
 // Open checkout session in a browser
-if (process.platform === 'darwin') {
-  // macOS
-  exec(`open ${url}`);
-} else if (process.platform === 'win32') {
-  // Windows
-  exec(`start "" "${url}"`, { shell: true });
-} else {
-  // Linux/Unix
-  open(url);
-}
+window.open(url, '_blank');
 ```
 
 ##### Ethereum (ETH) Fiat Top Up
 
-```ts
+```typescript
 const turbo = TurboFactory.unauthenticated({ token: 'ethereum' });
 
 const { url, winc, paymentAmount } = await turbo.createCheckoutSession({
@@ -469,7 +420,7 @@ const { url, winc, paymentAmount } = await turbo.createCheckoutSession({
 
 ##### Solana (SOL) Fiat Top Up
 
-```ts
+```typescript
 const turbo = TurboFactory.unauthenticated({ token: 'solana' });
 
 const { url, winc, paymentAmount } = await turbo.createCheckoutSession({
@@ -480,7 +431,7 @@ const { url, winc, paymentAmount } = await turbo.createCheckoutSession({
 
 ##### Polygon (POL / MATIC) Fiat Top Up
 
-```ts
+```typescript
 const turbo = TurboFactory.unauthenticated({ token: 'pol' });
 
 const { url, winc, paymentAmount } = await turbo.createCheckoutSession({
@@ -491,7 +442,7 @@ const { url, winc, paymentAmount } = await turbo.createCheckoutSession({
 
 ##### KYVE Fiat Top Up
 
-```ts
+```typescript
 const turbo = TurboFactory.unauthenticated({ token: 'kyve' });
 
 const { url, winc, paymentAmount } = await turbo.createCheckoutSession({
@@ -556,17 +507,8 @@ const { url, winc, paymentAmount, quotedPaymentAmount, adjustments } =
     promoCodes: ['MY_PROMO_CODE'], // promo codes require an authenticated client
   });
 
-// Open checkout session in a browser
-if (process.platform === 'darwin') {
-  // macOS
-  exec(`open ${url}`);
-} else if (process.platform === 'win32') {
-  // Windows
-  exec(`start "" "${url}"`, { shell: true });
-} else {
-  // Linux/Unix
-  open(url);
-}
+// open checkout session in a browser
+window.open(url, '_blank');
 ```
 
 #### `uploadFile({ fileStreamFactory, fileSizeFactory, signal, dataItemOpts })`
@@ -669,9 +611,19 @@ const { winc, status, id, ...fundResult } = await turbo.topUpWithTokens({
 });
 ```
 
+##### AR.IO Network (ARIO) Crypto Top Up
+
+```typescript
+const turbo = TurboFactory.authenticated({ signer, token: 'ario' });
+
+const { winc, status, id, ...fundResult } = await turbo.topUpWithTokens({
+  tokenAmount: ARIOToTokenAmount(100), // 100 $ARIO
+});
+```
+
 ##### Ethereum (ETH) Crypto Top Up
 
-```ts
+```typescript
 const turbo = TurboFactory.authenticated({ signer, token: 'ethereum' });
 
 const { winc, status, id, ...fundResult } = await turbo.topUpWithTokens({
@@ -681,7 +633,7 @@ const { winc, status, id, ...fundResult } = await turbo.topUpWithTokens({
 
 ##### Polygon (POL / MATIC) Crypto Top Up
 
-```ts
+```typescript
 const turbo = TurboFactory.authenticated({ signer, token: 'pol' });
 
 const { winc, status, id, ...fundResult } = await turbo.topUpWithTokens({
@@ -691,7 +643,7 @@ const { winc, status, id, ...fundResult } = await turbo.topUpWithTokens({
 
 ##### Eth on Base Network Crypto Top Up
 
-```ts
+```typescript
 const turbo = TurboFactory.authenticated({ signer, token: 'base-eth' });
 
 const { winc, status, id, ...fundResult } = await turbo.topUpWithTokens({
@@ -701,7 +653,7 @@ const { winc, status, id, ...fundResult } = await turbo.topUpWithTokens({
 
 ##### Solana (SOL) Crypto Top Up
 
-```ts
+```typescript
 const turbo = TurboFactory.authenticated({ signer, token: 'solana' });
 
 const { winc, status, id, ...fundResult } = await turbo.topUpWithTokens({
@@ -711,7 +663,7 @@ const { winc, status, id, ...fundResult } = await turbo.topUpWithTokens({
 
 ##### KYVE Crypto Top Up
 
-```ts
+```typescript
 const turbo = TurboFactory.authenticated({ signer, token: 'kyve' });
 
 const { winc, status, id, ...fundResult } = await turbo.topUpWithTokens({
@@ -754,7 +706,9 @@ const { givenApprovals, receivedApprovals } =
 
 ## CLI
 
-### Install CLI
+<!-- markdownlint-disable MD024 -->
+
+### Installation
 
 Global installation:
 
@@ -780,7 +734,9 @@ or
 yarn add -D @ardrive/turbo-sdk
 ```
 
-### CLI Usage
+<!-- markdownlint-disable MD024 -->
+
+### Usage
 
 ```shell
 turbo --help
@@ -806,6 +762,8 @@ Global options:
 - `-g, --gateway <url>` - Set a custom crypto gateway URL
 - `--upload-url <url>` - Set a custom upload service URL
 - `--payment-url <url>` - Set a custom payment service URL
+- `--cu-url <url>` - Set a custom AO compute unit URL
+- `--process-id <id>` - Set a custom target process ID for AO action
 - `-t, --token <token>` - Token type for the command or connected wallet (default: "arweave")
 
 Wallet options:
@@ -876,6 +834,15 @@ turbo crypto-fund --value 0.0001 --token kyve --private-key 'b27...45c'
 turbo crypto-fund --tx-id 'my-valid-arweave-fund-transaction-id' --token arweave
 ```
 
+```shell
+turbo crypto-fund --value 100 --token ario --wallet-file ../path/to/arweave/wallet/with/ario.json
+```
+
+```shell
+# Use a custom AO process ID and compute unit:
+turbo crypto-fund --value 100 --token ario --process-id agYcCFJtrMG6cqMuZfskIkFTGvUPddICmtQSBIoPdiA --cu-url https://cu.ao-testnet.xyz
+```
+
 ##### `upload-folder`
 
 Upload a folder of files and create and upload a manifest file for the folder upload to the Turbo Upload Service.