diff --git a/.c8rc b/.c8rc index 083c51e7..8e21c13f 100644 --- a/.c8rc +++ b/.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"] diff --git a/.mocharc b/.mocharc index 9c230ab0..1f8a9636 100644 --- a/.mocharc +++ b/.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, diff --git a/README.md b/README.md index fcbfa025..68be820e 100644 --- a/README.md +++ b/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 + + +``` + +## 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. diff --git a/bundle.cjs b/bundle.cjs index 2714e2dd..610c0629 100644 --- a/bundle.cjs +++ b/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: { diff --git a/examples/node/files/0_kb.txt b/examples/node/files/0_kb.txt new file mode 100644 index 00000000..e69de29b diff --git a/examples/node/index.cjs b/examples/node/index.cjs index 4b51ac34..a2277a59 100644 --- a/examples/node/index.cjs +++ b/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)); })(); diff --git a/examples/node/index.mjs b/examples/node/index.mjs index f32de8f9..1dc5987b 100644 --- a/examples/node/index.mjs +++ b/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)); })(); diff --git a/examples/web/index.html b/examples/web/index.html index f4f53754..6f365fe0 100644 --- a/examples/web/index.html +++ b/examples/web/index.html @@ -18,15 +18,43 @@