@ardrive/turbo-sdk 1.0.0-beta.3 → 1.0.0

package/README.md

@@ -5,6 +5,7 @@ Welcome to the `@ardrive/turbo-sdk`! This SDK provides functionality for interac
 ## Table of Contents
 
 - [Installation](#installation)
+- [Quick Start](#quick-start)
 - [Usage](#usage)
   - [NodeJS Environments](#nodejs)
     - [CommonJS](#commonjs)
@@ -13,7 +14,11 @@ Welcome to the `@ardrive/turbo-sdk`! This SDK provides functionality for interac
     - [Bundlers (Webpack, Rollup, ESbuild, etc.)](#bundlers-webpack-rollup-esbuild-etc)
     - [Browser](#browser)
   - [Typescript](#typescript)
-  - [Examples](./examples)
+- [APIs](#apis)
+  - [TurboFactory](#turbofactory)
+  - [TurboUnauthenticatedClient](#turbounauthenticatedclient)
+  - [TurboAuthenticatedClient](#turboauthenticatedclient)
+- [Examples](./examples)
 - [Contributions](#contributions)
 
 ## Installation
@@ -28,6 +33,57 @@ or
 yarn add @ardrive/turbo-sdk
 ```
 
+## Quick Start
+
+```typescript
+import { TurboFactory } from '@ardrive/turbo-sdk';
+
+// load your JWK from a file or generate a new one
+const jwk = fs.readFileSync('./my-jwk.json');
+const address = arweave.wallets.jwkToAddress(jwk);
+const turbo = TurboFactory.authenticated({ privateKey: jwk });
+
+// 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
+  });
+  // 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);
+}
+```
+
 ## 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.
@@ -127,7 +183,7 @@ 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.
+Types are exported from `./lib/types/[node/web]/index.d.ts` and should be automatically recognized, offering benefits such as type-checking and autocompletion.
 
 ## APIs
 
@@ -160,7 +216,7 @@ Types are exported from `./lib/types/index.d.ts` and should be automatically rec
   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.
+- `getFiatToAR({ currency })` - 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' });
@@ -178,6 +234,7 @@ Types are exported from `./lib/types/index.d.ts` and should be automatically rec
   const { winc, paymentAmount, quotedPaymentAmount, adjustments } =
     await turbo.getWincForFiat({
       amount: USD(100),
+      // promo codes require an authenticated client
     });
   ```
 
@@ -200,14 +257,14 @@ Types are exported from `./lib/types/index.d.ts` and should be automatically rec
   });
   ```
 
-- `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.
+- `createCheckoutSession({ amount, owner })` - Creates a Stripe checkout session for a Turbo Top Up with the provided amount, currency, owner. The returned URL can be opened in the browser, all payments are processed by Stripe. To leverage promo codes, see [TurboAuthenticatedClient].
 
   ```typescript
   const { url, winc, paymentAmount, quotedPaymentAmount, adjustments } =
     await turbo.createCheckoutSession({
       amount: USD(10.0), // $10.00 USD
       owner: publicArweaveAddress,
-      promoCodes: ['MY_PROMO_CODE'],
+      // promo codes require an authenticated client
     });
 
   // Open checkout session in a browser
@@ -231,14 +288,37 @@ Types are exported from `./lib/types/index.d.ts` and should be automatically rec
   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.
+- `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'],
+      promoCodes: ['MY_PROMO_CODE'], // promo codes require an authenticated client
+    });
+  ```
+
+- `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. Promo codes require an authenticated client.
+
+  ```typescript
+  const { url, winc, paymentAmount, quotedPaymentAmount, adjustments } =
+    await turbo.createCheckoutSession({
+      amount: USD(10.0), // $10.00 USD
+      owner: publicArweaveAddress,
+      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);
+  }
   ```
 
 - `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.
@@ -259,6 +339,5 @@ If you encounter any issues or have feature requests, please file an issue on ou
 
 [package.json]: ./package.json
 [examples]: ./examples
-[TurboUnauthenticatedClient]: #turboUnauthenticatedClient
-[TurboAuthenticatedClient]: #turboAuthenticatedClient
+[TurboAuthenticatedClient]: #turboauthenticatedclient
 [AbortSignal]: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ardrive/turbo-sdk",
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0",
   "main": "./lib/cjs/node/index.js",
   "types": "./lib/types/node/index.d.ts",
   "module": "./lib/esm/node/index.js",