feat(PE-4472): add uploadFile, uploadSignedDataItem implementations for node and web

.c8rc

@@ -1,7 +1,7 @@
 {
   "extension": [".ts"],
   "include": ["src/**/*.ts"],
-  "exclude": ["**/*.d.ts", "**/*.test.ts"],
+  "exclude": ["**/*.d.ts", "**/*.test.ts", "src/types/**/*.ts"],
   "all": true,
   "coverage": true,
   "reporter": ["text", "html"]

.mocharc

@@ -1,7 +1,14 @@
 {
-  "extension": ["ts"],
-  "spec": ["tests/**/*.test.ts", "src/**/*.test.ts"],
-  "require": ["ts-node/register/transpile-only"],
+  "extension": [
+    "ts"
+  ],
+  "spec": [
+    "tests/**/*.test.ts"
+  ],
+  "require": [
+    "ts-node/register/transpile-only",
+    "./mocha.setup.cjs"
+  ],
   "timeout": "10000",
   "parallel": false,
   "recursive": true,

README.md

@@ -1,3 +1,114 @@
-# turbo-sdk
+# @ardriveapp/turbo-sdk 🚀
 
-Hello developer, welcome to this 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.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage):
+
+  - [NodeJS Environments](#nodejs)
+    - [CommonJS](#commonjs)
+    - [ESM](#esm)
+  - [Web Environments](#web)
+    - [Bundlers (Webpack, Rollup, ESbuild, etc.)](#bundlers-webpack-rollup-esbuild-etc)
+    - [Browser](#browser)
+  - [Typescript](#typescript)
+  - [Examples](./examples)
+
+- [Contributions](#contributions)
+
+# Installation
+
+```shell
+npm install @ardrive/turbo-sdk
+```
+
+or
+
+```shell
+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.
+
+## Web
+
+# Bundlers (Webpack, Rollup, ESbuild, etc.)
+
+```javascript
+import { TurboFactory } from '@ardrive/turbo-sdk/web';
+
+const turbo = TurboFactory.unauthenticated({});
+const rates = await turbo.getFiatRates();
+```
+
+### Browser
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@ardrive/turbo-sdk"></script>
+<script>
+  const turbo = TurboFactory.unauthenticated({});
+  const rates = await turbo.getFiatRates();
+</script>
+```
+
+## NodeJS
+
+### CommonJS
+
+```javascript
+const { TurboFactory } = require('@ardrive/turbo-sdk/node');
+
+const turbo = TurboFactory.unauthenticated({});
+const rates = await turbo.getFiatRates();
+```
+
+### ESM
+
+```javascript
+import { TurboFactory } from '@ardrive/turbo-sdk/node';
+
+const turbo = TurboFactory.unauthenticated({});
+const rates = await turbo.getFiatRates();
+```
+
+## Typescript
+
+The SDK provides TypeScript typings. When you import the SDK in a TypeScript project:
+
+```typescript
+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.
+
+# APIs (WIP)
+
+## TurboFactory
+
+- `public()`
+- `private()`
+
+## TurboUnauthenticatedClient
+
+- `getFiatRates()`
+- `getFiatToAR()`
+- `getSupportedCountries()`
+- `getSupportedCurrencies()`
+- `getWincForFiat()`
+- `getUploadCosts()`
+- `uploadSignedDataItem()`
+
+## TurboAuthenticatedClient
+
+- `getBalance()`
+- `uploadFile()`
+
+# 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.

bundle.cjs

@@ -5,13 +5,14 @@ const stdLibBrowser = require('node-stdlib-browser');
 const bundle = async () => {
   console.log('Building web bundle esm.');
   const result = await build({
-    entryPoints: ['./src/index.ts'],
+    entryPoints: ['./src/web/index.ts'],
     bundle: true,
     platform: 'browser',
     target: ['esnext'],
     format: 'esm',
     globalName: 'turbo',
     plugins: [plugin(stdLibBrowser)],
+    tsconfig: './tsconfig.web.json',
     outfile: './bundles/web.bundle.min.js',
     inject: [require.resolve('node-stdlib-browser/helpers/esbuild/shim')],
     define: {

examples/node/index.cjs

@@ -1,25 +1,40 @@
-const Arweave = require('arweave');
-const TurboFactory = require('../../lib/index.js');
-
 (async () => {
+  const { default: Arweave } = await import('arweave');
+  const { TurboFactory, TurboUnauthenticatedPaymentService } = await import(
+    '../../lib/node/index.js'
+  );
+  const path = require('path');
+  const fs = require('fs');
   /**
    * Fetching rates using an unauthenticated Turbo client.
    */
-  const turbo = TurboFactory.init();
-  const rates = await turbo.getRates();
+  const turbo = TurboFactory.unauthenticated();
+  const rates = await turbo.getFiatRates();
   console.log('Fetched rates:', JSON.stringify(rates, null, 2));
 
+  /**
+   * Alternatively instantiate your own clients independently.
+   */
+  const paymentService = new TurboUnauthenticatedPaymentService({
+    url: 'https://payment.ardrive.dev',
+  });
+  const supportedCurrencies = await paymentService.getSupportedCurrencies();
+  console.log(
+    'Supported currencies:',
+    JSON.stringify(supportedCurrencies, null, 2),
+  );
+
   /**
    * Create a new arweave private key
    */
-  const arweave = Arweave.init();
+  const arweave = new Arweave({});
   const jwk = await Arweave.crypto.generateJWK();
   const address = await arweave.wallets.jwkToAddress(jwk);
 
   /**
    * Use the arweave key to create an authenticated turbo client
    */
-  const turboAuthClient = TurboFactory.init({ privateKey: jwk });
+  const turboAuthClient = TurboFactory.authenticated({ privateKey: jwk });
 
   /**
    * Fetch the balance for the private key.
@@ -38,11 +53,22 @@ const TurboFactory = require('../../lib/index.js');
   );
 
   /**
-   * Fetch the estimated amount of winc returned for $1 USD
+   * Fetch the estimated amount of winc returned for 10 USD (1000 cents).
    */
   const estimatedWinc = await turboAuthClient.getWincForFiat({
     amount: 1000,
     currency: 'usd',
   });
   console.log('10 USD to winc:', estimatedWinc);
+
+  /**
+   * Post local files to the Turbo service.
+   */
+  console.log('Posting raw file to Turbo service...');
+  const filePath = path.join(__dirname, './files/0_kb.txt');
+  const uploadResult = await turboAuthClient.uploadFile({
+    fileStreamFactory: () => fs.createReadStream(filePath),
+    signal: AbortSignal.timeout(10_000), // cancel the upload after 10 seconds
+  });
+  console.log(JSON.stringify(uploadResult, null, 2));
 })();

examples/node/index.mjs

@@ -1,22 +1,38 @@
 import Arweave from 'arweave';
+import fs from 'fs';
 
-import { TurboFactory } from '../../lib/index.js';
+import {
+  TurboFactory,
+  TurboUnauthenticatedPaymentService,
+} from '../../lib/node/index.js';
 
 (async () => {
   /**
    * Fetching rates using an unauthenticated Turbo client.
    */
-  const turbo = TurboFactory.init();
+  const turbo = TurboFactory.unauthenticated();
   const rates = await turbo.getFiatRates();
   console.log('Fetched rates:', JSON.stringify(rates, null, 2));
 
+  /*
+   * Alternatively instantiate your own clients independently.
+   */
+  const paymentService = new TurboUnauthenticatedPaymentService({
+    url: 'https://payment.ardrive.dev',
+  });
+  const supportedCurrencies = await paymentService.getSupportedCurrencies();
+  console.log(
+    'Supported currencies:',
+    JSON.stringify(supportedCurrencies, null, 2),
+  );
+
   /**
    * Fetching balance using an authenticated Turbo client.
    */
-  const arweave = Arweave.init();
+  const arweave = new Arweave.init();
   const jwk = await Arweave.crypto.generateJWK();
   const address = await arweave.wallets.jwkToAddress(jwk);
-  const turboAuthClient = TurboFactory.init({ privateKey: jwk });
+  const turboAuthClient = TurboFactory.authenticated({ privateKey: jwk });
   const balance = await turboAuthClient.getBalance();
   console.log(
     'Balance:',
@@ -31,11 +47,22 @@ import { TurboFactory } from '../../lib/index.js';
   );
 
   /**
-   * Fetch the estimated amount of winc returned for $1 USD
+   * Fetch the estimated amount of winc returned for 10 USD (1000 cents).
    */
   const estimatedWinc = await turboAuthClient.getWincForFiat({
     amount: 1000,
     currency: 'usd',
   });
   console.log('10 USD to winc:', estimatedWinc);
+
+  /**
+   * Post local files to the Turbo service.
+   */
+  console.log('Posting raw files to Turbo service...');
+  const filePath = new URL('files/0_kb.txt', import.meta.url).pathname;
+  const uploadResult = await turboAuthClient.uploadFile({
+    fileStreamFactory: () => fs.createReadStream(filePath),
+    signal: AbortSignal.timeout(10_000), // cancel the upload after 10 second
+  });
+  console.log(JSON.stringify(uploadResult, null, 2));
 })();