@ardrive/turbo-sdk

@ardriveapp/turbo-sdk 🚀

Welcome to the @ardrive/turbo-sdk! This SDK provides functionality for interacting with the Turbo Upload and Payment Services and is available for both NodeJS and Web environments.

Table of Contents

• Installation
• Usage
  • NodeJS Environments
    • CommonJS
    • ESM
  • Web Environments
    • Bundlers (Webpack, Rollup, ESbuild, etc.)
    • Browser
  • Typescript
  • Examples
• Contributions

Installation

npm install @ardrive/turbo-sdk

or

yarn add @ardrive/turbo-sdk

Usage

The SDK is provided in both CommonJS and ESM formats, and it's compatible with bundlers such as Webpack, Rollup, and ESbuild. Utilize the appropriate named exports provided by this SDK's package.json based on your project's configuration. Refer to the examples directory to see how to use the SDK in various environments.

Web

Bundlers (Webpack, Rollup, ESbuild, etc.)

import { TurboFactory } from '@ardrive/turbo-sdk';

const turbo = TurboFactory.unauthenticated();
const rates = await turbo.getFiatRates();

Browser

<script src="https://cdn.jsdelivr.net/npm/@ardrive/turbo-sdk"></script>
<script>
  const turbo = TurboFactory.unauthenticated();
  const rates = await turbo.getFiatRates();
</script>

NodeJS

CommonJS

Project's package.json:

{
  "type": "commonjs" // or absent
}

Project's tsconfig.json:

{
  "compilerOptions": {
    "module": "CommonJS",
    "moduleResolution": "Node",
    "skipLibCheck": true
  }
}

Usage:

const { TurboFactory } = require('@ardrive/turbo-sdk');

const turbo = TurboFactory.unauthenticated();
const rates = await turbo.getFiatRates();

ESM

Project's package.json:

{
  "type": "module"
}

Project's tsconfig.json:

{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "skipLibCheck": true
  }
}

Usage:

import { TurboFactory } from '@ardrive/turbo-sdk/node';

const turbo = TurboFactory.unauthenticated();
const rates = await turbo.getFiatRates();

Typescript

The SDK provides TypeScript types. When you import the SDK in a TypeScript project:

import { TurboFactory } from '@ardrive/turbo-sdk/web';

// or '@ardrive/turbo-sdk/node' for Node.js projects

Types are exported from ./lib/types/index.d.ts and should be automatically recognized, offering benefits such as type-checking and autocompletion.

APIs

TurboFactory

• unauthenticated() - Creates an instance of a client that accesses Turbo's unauthenticated services.

  const turbo = TurboFactory.unauthenticated();
  

• authenticated() - Creates an instance of a client that accesses Turbo's authenticated and unauthenticated services.

  const jwk = await arweave.crypto.generateJWK();
  const turbo = TurboFactory.authenticated({ privateKey: jwk });
  

TurboUnauthenticatedClient

• getSupportedCurrencies() - Returns the list of currencies supported by the Turbo Payment Service for topping up a user balance of AR Credits (measured in Winston Credits, or winc).

  const currencies = await turbo.getSupportedCurrencies();
  

• getSupportedCountries() - Returns the list of countries supported by the Turbo Payment Service's top up workflow.

  const countries = await turbo.getSupportedCountries();
  

• getFiatToAR() - Returns the current raw fiat to AR conversion rate for a specific currency as reported by third-party pricing oracles.

  const fiatToAR = await turbo.getFiatToAR({ currency: 'USD' });
  

• getFiatRates() - Returns the current fiat rates for 1 GiB of data for supported currencies, including all top-up adjustments and fees.

  const rates = await turbo.getFiatRates();
  

• getWincForFiat({ amount }) - Returns the current amount of Winston Credits including all adjustments for the provided fiat currency, amount. To leverage promo codes, see TurboAuthenticatedClient.

  const { winc, paymentAmount, quotedPaymentAmount, adjustments } =
    await turbo.getWincForFiat({
      amount: USD(100),
    });
  

• getUploadCosts({ bytes }) - Returns the estimated cost in Winston Credits for the provided file sizes, including all upload adjustments and fees.

  const [uploadCostForFile] = await turbo.getUploadCosts({ bytes: [1024] });
  const { winc, adjustments } = uploadCostForFile;
  

• uploadSignedDataItem({ dataItemStreamFactory, dataItemSizeFactory, signal }) - Uploads a signed data item. The provided dataItemStreamFactory should produce a NEW signed data item stream each time is it invoked. The dataItemSizeFactory is a function that returns the size of the file. The signal is an optional AbortSignal that can be used to cancel the upload or timeout the request.

  const filePath = path.join(__dirname, './my-signed-data-item');
  const dataItemSize = fs.statSync(filePath).size;
  const uploadResponse = await turbo.uploadSignedDataItem({
    dataItemStreamFactory: () => fs.createReadStream(filePath),
    dataItemSizeFactory: () => dataItemSize,
    signal: AbortSignal.timeout(10_000), // cancel the upload after 10 seconds
  });
  

• createCheckoutSession({ amount, owner, promoCodes }) - Creates a Stripe checkout session for a Turbo Top Up with the provided amount, currency, owner, and optional promo codes. The returned URL can be opened in the browser, all payments are processed by Stripe.

  const { url, winc, paymentAmount, quotedPaymentAmount, adjustments } =
    await turbo.createCheckoutSession({
      amount: USD(10.0), // $10.00 USD
      owner: publicArweaveAddress,
      promoCodes: ['MY_PROMO_CODE'],
    });
  
  // 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);
  }
  

TurboAuthenticatedClient

• getBalance() - Issues a signed request to get the credit balance of a wallet measured in AR (measured in Winston Credits, or winc).

  const { winc: balance } = await turbo.getBalance();
  

• getWincForFiat({ amount, promoCodes }) - Returns the current amount of Winston Credits including all adjustments for the provided fiat currency, amount, and optional promo codes. Note: promo codes require an authenticated client.

  const { winc, paymentAmount, quotedPaymentAmount, adjustments } =
    await turbo.getWincForFiat({
      amount: USD(100),
      promoCodes: ['MY_PROMO_CODE'],
    });
  

• uploadFile({ fileStreamFactory, fileSizeFactory, signal }) - Signs and uploads a raw file. The provided fileStreamFactory should produce a NEW file data stream each time is it invoked. The fileSizeFactory is a function that returns the size of the file. The signal is an optional AbortSignal that can be used to cancel the upload or timeout the request.

  const filePath = path.join(__dirname, './my-unsigned-file.txt');
  const fileSize = fs.stateSync(filePath).size;
  const uploadResult = await turbo.uploadFile({
    fileStreamFactory: () => fs.createReadStream(filePath),
    fileSizeFactory: () => fileSize,
    // no timeout or AbortSignal provided
  });
  

Contributions

If you encounter any issues or have feature requests, please file an issue on our GitHub repository. Contributions, pull requests, and feedback are both welcome and encouraged.