@ardrive/turbo-sdk 1.0.0-alpha.21 → 1.0.0-alpha.23

package/README.md

@@ -1,12 +1,11 @@
 # @ardriveapp/turbo-sdk 🚀
 
-Welcome to the `@ardrive/turbo-sdk`! This SDK provides functionalities for interacting with the Turbo Upload and Payment Services. It is available in both NodeJS and Web environments.
+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](#installation)
-- [Usage](#usage):
-
+- [Usage](#usage)
   - [NodeJS Environments](#nodejs)
     - [CommonJS](#commonjs)
     - [ESM](#esm)
@@ -15,7 +14,6 @@ Welcome to the `@ardrive/turbo-sdk`! This SDK provides functionalities for inter
     - [Browser](#browser)
   - [Typescript](#typescript)
   - [Examples](./examples)
-
 - [Contributions](#contributions)
 
 ## Installation
@@ -32,14 +30,14 @@ yarn add @ardrive/turbo-sdk
 
 ## Usage
 
-The SDK is available in both CommonJS and ESM formats and is compatible with bundlers such as Webpack, Rollup, and ESbuild.
+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.)
 
 ```javascript
-import { TurboFactory } from '@ardrive/turbo-sdk/web';
+import { TurboFactory } from '@ardrive/turbo-sdk';
 
 const turbo = TurboFactory.unauthenticated({});
 const rates = await turbo.getFiatRates();
@@ -59,14 +57,58 @@ const rates = await turbo.getFiatRates();
 
 #### CommonJS
 
+Project's `package.json`:
+
+```json
+{
+  "type": "commonjs" // or absent
+}
+```
+
+tsconfig's `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "module": "CommonJS",
+    "moduleResolution": "Node",
+    "skipLibCheck": true
+  }
+}
+```
+
+Usage:
+
 ```javascript
-const { TurboFactory } = require('@ardrive/turbo-sdk/node');
+const { TurboFactory } = require('@ardrive/turbo-sdk');
 
 const turbo = TurboFactory.unauthenticated({});
 const rates = await turbo.getFiatRates();
 ```
 
-### ESM
+#### ESM
+
+Project's `package.json`:
+
+```json
+{
+  "type": "module"
+}
+```
+
+tsconfig's `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "skipLibCheck": true
+  }
+}
+```
+
+Usage:
 
 ```javascript
 import { TurboFactory } from '@ardrive/turbo-sdk/node';
@@ -77,7 +119,7 @@ const rates = await turbo.getFiatRates();
 
 ### Typescript
 
-The SDK provides TypeScript typings. When you import the SDK in a TypeScript project:
+The SDK provides TypeScript types. When you import the SDK in a TypeScript project:
 
 ```typescript
 import Ardrive from '@ardrive/turbo-sdk/web';
@@ -85,30 +127,126 @@ import Ardrive from '@ardrive/turbo-sdk/web';
 // or '@ardrive/turbo-sdk/node' for Node.js projects
 ```
 
-The provided typings (`./lib/types/index.d.ts`) will be automatically recognized, offering type checking and autocompletion benefits.
+Types are exported from `./lib/types/index.d.ts` and should be automatically recognized, offering benefits such as type-checking and autocompletion.
 
-## APIs (WIP)
+## APIs
 
 ### TurboFactory
 
-- `public()`
-- `private()`
+- `unauthenticated()` - Creates an instance of a client that accesses Turbo's unauthenticated services.
+
+  ```typescript
+  const turbo = TurboFactory.unauthenticated({});
+  ```
+
+- `authenticated()` - Creates an instance of a client that accesses Turbo's authenticated and unauthenticated services.
+
+  ```typescript
+  const jwk = await arweave.crypto.generateJWK();
+  const turbo = TurboFactory.authenticated({ privateKey: jwk });
+  ```
 
 ### TurboUnauthenticatedClient
 
-- `getFiatRates()`
-- `getFiatToAR()`
-- `getSupportedCountries()`
-- `getSupportedCurrencies()`
-- `getWincForFiat()`
-- `getUploadCosts()`
-- `uploadSignedDataItem()`
+- `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).
+
+  ```typescript
+  const currencies = await turbo.getSupportedCurrencies();
+  ```
+
+- `getSupportedCountries()` - Returns the list of countries supported by the Turbo Payment Service's top up workflow.
+
+  ```typescript
+  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.
+
+  ```typescript
+  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.
+
+  ```typescript
+  const rates = await turbo.getFiatRates();
+  ```
+
+- `getWincForFiat({ amount, promoCodes })` - Returns the current amount of Winston Credits including all adjustments for the provided fiat currency, amount, and optional promo codes.
+
+  ```typescript
+  const { winc, paymentAmount, quotedPaymentAmount, adjustments } =
+    await turbo.getWincForFiat({
+      amount: USD(100),
+      promoCodes: ['MY_PROMO_CODE'],
+    });
+  ```
+
+- `getUploadCosts({ bytes })` - Returns the estimated cost in Winston Credits for the provided file sizes, including all upload adjustments and fees.
+
+  ```typescript
+  const costs = await turbo.getUploadCosts({ bytes: [1000, 2000] });
+  ```
+
+- `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.
+
+  ```typescript
+  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.
+
+  ```typescript
+  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()`
-- `uploadFile()`
+- `getBalance()` - Issues a signed request to get the credit balance of a wallet measured in AR (measured in Winston Credits, or winc).
+
+  ```typescript
+  const balance = await turbo.getBalance();
+  ```
+
+- `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.
+
+  ```typescript
+  const filePath = path.join(__dirname, './my-unsigned-file.txt');
+  const fileSize = fs.stateSync(filePath).size;
+  const uploadResult = await turboAuthClient.uploadFile({
+    fileStreamFactory: () => fs.createReadStream(filePath),
+    fileSizeFactory: () => fileSize,
+  });
+  ```
 
 ## Contributions
 
-If you encounter any issues or have feature requests, please file an issue on our GitHub repository. Contributions, pull requests, and feedback are welcome and encouraged.
+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.
+
+[package.json]: ./package.json
+[examples]: ./examples
+[TurboUnauthenticatedClient]: #turboUnauthenticatedClient
+[TurboAuthenticatedClient]: #turboAuthenticatedClient

package/bundles/web.bundle.min.js

@@ -47404,24 +47404,24 @@ var TurboUnauthenticatedPaymentService = class {
       retryConfig
     });
   }
-  async getFiatRates() {
+  getFiatRates() {
     return this.httpService.get({
       endpoint: "/rates"
     });
   }
-  async getFiatToAR({
+  getFiatToAR({
     currency
   }) {
     return this.httpService.get({
       endpoint: `/rates/${currency}`
     });
   }
-  async getSupportedCountries() {
+  getSupportedCountries() {
     return this.httpService.get({
       endpoint: "/countries"
     });
   }
-  async getSupportedCurrencies() {
+  getSupportedCurrencies() {
     return this.httpService.get({
       endpoint: "/currencies"
     });
@@ -47437,10 +47437,37 @@ var TurboUnauthenticatedPaymentService = class {
     const wincCostsForBytes = await Promise.all(fetchPricePromises);
     return wincCostsForBytes;
   }
-  async getWincForFiat({ amount, currency }) {
+  getWincForFiat({
+    amount
+  }) {
+    const { amount: paymentAmount, type: currencyType } = amount;
     return this.httpService.get({
-      endpoint: `/price/${currency}/${amount}`
+      endpoint: `/price/${currencyType}/${paymentAmount}`
+    });
+  }
+  appendPromoCodesToQuery(promoCodes) {
+    const promoCodesQuery = promoCodes.join(",");
+    return promoCodesQuery ? `?promoCode=${promoCodesQuery}` : "";
+  }
+  async getCheckout({ amount, owner, promoCodes = [] }, headers) {
+    const { amount: paymentAmount, type: currencyType } = amount;
+    const endpoint = `/top-up/checkout-session/${owner}/${currencyType}/${paymentAmount}${this.appendPromoCodesToQuery(
+      promoCodes
+    )}`;
+    const { adjustments, paymentSession, topUpQuote } = await this.httpService.get({
+      endpoint,
+      headers
     });
+    return {
+      winc: topUpQuote.winstonCreditAmount,
+      adjustments,
+      url: paymentSession.url,
+      paymentAmount: topUpQuote.paymentAmount,
+      quotedPaymentAmount: topUpQuote.quotedPaymentAmount
+    };
+  }
+  createCheckoutSession(params) {
+    return this.getCheckout(params);
   }
 };
 var TurboAuthenticatedPaymentService = class extends TurboUnauthenticatedPaymentService {
@@ -47461,6 +47488,21 @@ var TurboAuthenticatedPaymentService = class extends TurboUnauthenticatedPayment
     });
     return balance.winc ? balance : { winc: "0" };
   }
+  async getWincForFiat({
+    amount,
+    promoCodes = []
+  }) {
+    return this.httpService.get({
+      endpoint: `/price/${amount.type}/${amount.amount}${this.appendPromoCodesToQuery(promoCodes)}`,
+      headers: await this.signer.generateSignedRequestHeaders()
+    });
+  }
+  async createCheckoutSession(params) {
+    return this.getCheckout(
+      params,
+      await this.signer.generateSignedRequestHeaders()
+    );
+  }
 };
 
 // src/common/turbo.ts
@@ -47480,14 +47522,17 @@ var TurboUnauthenticatedUploadService = class {
   }
   async uploadSignedDataItem({
     dataItemStreamFactory,
+    dataItemSizeFactory,
     signal
   }) {
+    const fileSize = dataItemSizeFactory();
     return this.httpService.post({
       endpoint: `/tx`,
       signal,
       data: dataItemStreamFactory(),
       headers: {
-        "content-type": "application/octet-stream"
+        "content-type": "application/octet-stream",
+        "content-length": `${fileSize}`
       }
     });
   }
@@ -47503,17 +47548,22 @@ var TurboAuthenticatedUploadService = class extends TurboUnauthenticatedUploadSe
   }
   async uploadFile({
     fileStreamFactory,
+    fileSizeFactory,
     signal
   }) {
-    const signedDataItem = await this.signer.signDataItem({
-      fileStreamFactory
+    const { dataItemStreamFactory, dataItemSizeFactory } = await this.signer.signDataItem({
+      fileStreamFactory,
+      fileSizeFactory
     });
+    const signedDataItem = dataItemStreamFactory();
+    const fileSize = dataItemSizeFactory();
     return this.httpService.post({
       endpoint: `/tx`,
       signal,
       data: signedDataItem,
       headers: {
-        "content-type": "application/octet-stream"
+        "content-type": "application/octet-stream",
+        "content-length": `${fileSize}`
       }
     });
   }
@@ -47531,7 +47581,7 @@ var TurboUnauthenticatedClient = class {
   /**
    * Returns the supported fiat currency conversion rate for 1AR based on current market prices.
    */
-  async getFiatToAR({
+  getFiatToAR({
     currency
   }) {
     return this.paymentService.getFiatToAR({ currency });
@@ -47542,25 +47592,25 @@ var TurboUnauthenticatedClient = class {
    * Note: this does not take into account varying adjustments and promotions for different sizes of data. If you want to calculate the total
    * cost in 'winc' for a given number of bytes, use getUploadCosts.
    */
-  async getFiatRates() {
+  getFiatRates() {
     return this.paymentService.getFiatRates();
   }
   /**
    * Returns a comprehensive list of supported countries that can purchase credits through the Turbo Payment Service.
    */
-  async getSupportedCountries() {
+  getSupportedCountries() {
     return this.paymentService.getSupportedCountries();
   }
   /**
    * Returns a list of all supported fiat currencies.
    */
-  async getSupportedCurrencies() {
+  getSupportedCurrencies() {
     return this.paymentService.getSupportedCurrencies();
   }
   /**
    * Determines the price in 'winc' to upload one data item of a specific size in bytes, including all Turbo cost adjustments and fees.
    */
-  async getUploadCosts({
+  getUploadCosts({
     bytes
   }) {
     return this.paymentService.getUploadCosts({ bytes });
@@ -47568,24 +47618,29 @@ var TurboUnauthenticatedClient = class {
   /**
    * Determines the amount of 'winc' that would be returned for a given currency and amount, including all Turbo cost adjustments and fees.
    */
-  async getWincForFiat({
-    amount,
-    currency
-  }) {
-    return this.paymentService.getWincForFiat({ amount, currency });
+  getWincForFiat(params) {
+    return this.paymentService.getWincForFiat(params);
   }
   /**
    * Uploads a signed data item to the Turbo Upload Service.
    */
-  async uploadSignedDataItem({
+  uploadSignedDataItem({
     dataItemStreamFactory,
+    dataItemSizeFactory,
     signal
   }) {
     return this.uploadService.uploadSignedDataItem({
       dataItemStreamFactory,
+      dataItemSizeFactory,
       signal
     });
   }
+  /**
+   * Creates a Turbo Checkout Session for a given amount and currency.
+   */
+  createCheckoutSession(params) {
+    return this.paymentService.createCheckoutSession(params);
+  }
 };
 var TurboAuthenticatedClient = class extends TurboUnauthenticatedClient {
   constructor({
@@ -47597,17 +47652,22 @@ var TurboAuthenticatedClient = class extends TurboUnauthenticatedClient {
   /**
    * Returns the current balance of the user's wallet in 'winc'.
    */
-  async getBalance() {
+  getBalance() {
     return this.paymentService.getBalance();
   }
   /**
    * Signs and uploads raw data to the Turbo Upload Service.
    */
-  async uploadFile({
+  uploadFile({
     fileStreamFactory,
+    fileSizeFactory,
     signal
   }) {
-    return this.uploadService.uploadFile({ fileStreamFactory, signal });
+    return this.uploadService.uploadFile({
+      fileStreamFactory,
+      fileSizeFactory,
+      signal
+    });
   }
 };
 
@@ -47633,6 +47693,34 @@ var TurboBaseFactory = class {
 // src/common/index.ts
 init_shim();
 
+// src/common/currency.ts
+init_shim();
+var ZeroDecimalCurrency = class {
+  constructor(amount, type) {
+    this.amount = amount;
+    this.type = type;
+  }
+};
+var TwoDecimalCurrency = class {
+  constructor(a, type) {
+    this.a = a;
+    this.type = type;
+  }
+  get amount() {
+    return this.a * 100;
+  }
+};
+var USD = (usd) => new TwoDecimalCurrency(usd, "usd");
+var EUR = (eur) => new TwoDecimalCurrency(eur, "eur");
+var GBP = (gbp) => new TwoDecimalCurrency(gbp, "gbp");
+var CAD = (cad) => new TwoDecimalCurrency(cad, "cad");
+var AUD = (aud) => new TwoDecimalCurrency(aud, "aud");
+var INR = (inr) => new TwoDecimalCurrency(inr, "inr");
+var SGD = (sgd) => new TwoDecimalCurrency(sgd, "sgd");
+var HKD = (hkd) => new TwoDecimalCurrency(hkd, "hkd");
+var BRL = (brl) => new TwoDecimalCurrency(brl, "brl");
+var JPY = (jpy) => new ZeroDecimalCurrency(jpy, "jpy");
+
 // src/web/signer.ts
 init_shim();
 
@@ -55555,19 +55643,22 @@ function toB64Url(buffer) {
 // src/utils/readableStream.ts
 init_shim();
 async function readableStreamToBuffer({
-  stream
+  stream,
+  size
 }) {
   const reader = stream.getReader();
-  const chunks = [];
+  const buffer = import_buffer.Buffer.alloc(size);
+  let offset = 0;
   let done = false;
   while (!done) {
     const { done: streamDone, value } = await reader.read();
     done = streamDone;
     if (!done) {
-      chunks.push(value);
+      buffer.set(value, offset);
+      offset += value.byteLength;
     }
   }
-  return import_buffer.Buffer.concat(chunks);
+  return buffer;
 }
 
 // src/web/signer.ts
@@ -55578,15 +55669,20 @@ var TurboWebArweaveSigner = class {
     this.signer = new ArweaveSigner(this.privateKey);
   }
   async signDataItem({
-    fileStreamFactory
+    fileStreamFactory,
+    fileSizeFactory
   }) {
     const buffer = await readableStreamToBuffer({
-      stream: fileStreamFactory()
-      // TODO: add payload size to get performance improvements
+      stream: fileStreamFactory(),
+      size: fileSizeFactory()
     });
-    const signedDataItem = createData(buffer, this.signer);
+    const signedDataItem = createData(buffer, this.signer, {});
     await signedDataItem.sign(this.signer);
-    return signedDataItem.getRaw();
+    return {
+      // while this returns a Buffer - it needs to match our return type for uploading
+      dataItemStreamFactory: () => signedDataItem.getRaw(),
+      dataItemSizeFactory: () => signedDataItem.getRaw().length
+    };
   }
   // NOTE: this might be better in a parent class or elsewhere - easy enough to leave in here now and does require specific environment version of crypto
   async generateSignedRequestHeaders() {
@@ -55628,6 +55724,15 @@ var TurboFactory = class extends TurboBaseFactory {
 // src/types.ts
 init_shim();
 export {
+  AUD,
+  BRL,
+  CAD,
+  EUR,
+  GBP,
+  HKD,
+  INR,
+  JPY,
+  SGD,
   TurboAuthenticatedClient,
   TurboAuthenticatedPaymentService,
   TurboAuthenticatedUploadService,
@@ -55635,7 +55740,10 @@ export {
   TurboUnauthenticatedClient,
   TurboUnauthenticatedPaymentService,
   TurboUnauthenticatedUploadService,
-  TurboWebArweaveSigner
+  TurboWebArweaveSigner,
+  TwoDecimalCurrency,
+  USD,
+  ZeroDecimalCurrency
 };
 /*! Bundled license information:
 

package/lib/cjs/common/currency.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JPY = exports.BRL = exports.HKD = exports.SGD = exports.INR = exports.AUD = exports.CAD = exports.GBP = exports.EUR = exports.USD = exports.TwoDecimalCurrency = exports.ZeroDecimalCurrency = void 0;
+class ZeroDecimalCurrency {
+    constructor(amount, type) {
+        this.amount = amount;
+        this.type = type;
+    }
+}
+exports.ZeroDecimalCurrency = ZeroDecimalCurrency;
+class TwoDecimalCurrency {
+    constructor(a, type) {
+        this.a = a;
+        this.type = type;
+    }
+    get amount() {
+        return this.a * 100;
+    }
+}
+exports.TwoDecimalCurrency = TwoDecimalCurrency;
+// Two decimal currencies that are supported by the Turbo API
+const USD = (usd) => new TwoDecimalCurrency(usd, 'usd');
+exports.USD = USD;
+const EUR = (eur) => new TwoDecimalCurrency(eur, 'eur');
+exports.EUR = EUR;
+const GBP = (gbp) => new TwoDecimalCurrency(gbp, 'gbp');
+exports.GBP = GBP;
+const CAD = (cad) => new TwoDecimalCurrency(cad, 'cad');
+exports.CAD = CAD;
+const AUD = (aud) => new TwoDecimalCurrency(aud, 'aud');
+exports.AUD = AUD;
+const INR = (inr) => new TwoDecimalCurrency(inr, 'inr');
+exports.INR = INR;
+const SGD = (sgd) => new TwoDecimalCurrency(sgd, 'sgd');
+exports.SGD = SGD;
+const HKD = (hkd) => new TwoDecimalCurrency(hkd, 'hkd');
+exports.HKD = HKD;
+const BRL = (brl) => new TwoDecimalCurrency(brl, 'brl');
+exports.BRL = BRL;
+// Zero decimal currencies that are supported by the Turbo API
+const JPY = (jpy) => new ZeroDecimalCurrency(jpy, 'jpy');
+exports.JPY = JPY;

package/lib/cjs/common/index.js

@@ -33,3 +33,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./upload.js"), exports);
 __exportStar(require("./payment.js"), exports);
 __exportStar(require("./turbo.js"), exports);
+__exportStar(require("./currency.js"), exports);