@autonomys/auto-drive 1.0.6 → 1.0.8

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2024 Autonomys Network (autonomys.xyz)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+1. **Attribution**: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+2. **No Warranty**: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+3. **Limitation of Liability**: IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+---

package/README.md

@@ -1,8 +1,14 @@
-# auto-drive
+# Autonomys Auto Drive SDK
 
-## auto-drive API Tools
+![Autonomys Banner](https://github.com/autonomys/auto-sdk/blob/main/.github/images/autonomys-banner.webp)
 
-The `auto-drive` package provides a set of tools to interact with the auto-drive API. Below are some key functionalities:
+[![Latest Github release](https://img.shields.io/github/v/tag/autonomys/auto-sdk.svg)](https://github.com/autonomys/auto-sdk/tags)
+[![Build status of the main branch on Linux/OSX](https://img.shields.io/github/actions/workflow/status/autonomys/auto-sdk/build.yaml?branch=main&label=Linux%2FOSX%20build)](https://github.com/autonomys/auto-sdk/actions/workflows/build.yaml)
+[![npm version](https://badge.fury.io/js/@autonomys%2Fauto-drive.svg)](https://badge.fury.io/js/@autonomys/auto-drive)
+
+## Overview
+
+The `auto-drive` package provides a set of tools to interact with the Autonomys Auto-Drive API. Below are some key functionalities:
 
 ### Installation
 
@@ -14,21 +20,21 @@ yarn add @autonomys/auto-drive
 
 ### How to use it?
 
-### Example Usage
+### How to upload a file from filepath? (Not available in browser)
 
-Here is an example of how to use the `uploadFile` method to upload a file with optional encryption and compression:
+Here is an example of how to use the `uploadFileFromFilepath` method to upload a file with optional encryption and compression:
 
 ```typescript
-import { uploadFile } from '@autonomys/auto-drive'
+import { uploadFileFromFilepath } from '@autonomys/auto-drive'
 
-const api = new AutoDriveApi() // Initialize your API instance
+const api = createAutoDriveApi({ apiKey: 'your-api-key' }) // Initialize your API instance with API key
 const filePath = 'path/to/your/file.txt' // Specify the path to your file
 const options = {
   password: 'your-encryption-password', // Optional: specify a password for encryption
   compression: true,
 }
 
-uploadFile(api, filePath, options)
+const uploadObservable = uploadFile(api, filePath, options)
   .then(() => {
     console.log('File uploaded successfully!')
   })
@@ -37,38 +43,197 @@ uploadFile(api, filePath, options)
   })
 ```
 
-### Example Usage of Download
-
-Here is an example of how to use the `downloadFile` method to download a file from the server:
+### How to upload [File](https://developer.mozilla.org/en-US/docs/Web/API/File) interface
 
 ```typescript
-import { getRoots } from '@autonomys/auto-drive'
+import { uploadFileFromFilepath } from '@autonomys/auto-drive'
 
-const api = new AutoDriveApi() // Initialize your API instance
+const api = createAutoDriveApi({ apiKey: 'your-api-key' }) // Initialize your API instance with API key
+const filePath = 'path/to/your/file.txt' // Specify the path to your file
+const options = {
+  password: 'your-encryption-password', // Optional: specify a password for encryption
+  compression: true,
+}
 
-getRoots(api)
-  .then((roots) => {
-    console.log('Root directories:', roots)
+const uploadObservable = uploadFile(api, filePath, options)
+  .then(() => {
+    console.log('File uploaded successfully!')
   })
   .catch((error) => {
-    console.error('Error retrieving root directories:', error)
+    console.error('Error uploading file:', error)
   })
 ```
 
-### Example Usage of getRoots
+### How to upload a file from a custom interface?
 
-Here is an example of how to use the `getRoots` method to retrieve the root directories:
+Some times you might have a custom interface that doesn't fit either File or filepath. For those cases exists the interface GenericFile:
 
 ```typescript
-import { getRoots } from '@autonomys/auto-drive'
+export interface GenericFile {
+  read(): AsyncIterable<Buffer> // A buffer generator function that will output the bytes of the file
+  name: string
+  mimeType?: string
+  size: number
+  path: string // Could be ignored in file upload
+}
+```
 
-const api = new AutoDriveApi() // Initialize your API instance
+For more info about asynn generator visit [this website](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncGenerator).
 
-getRoots(api)
-  .then((roots) => {
-    console.log('Root directories:', roots)
+You could upload any file that could be represented in that way. For example, uploading a file as a `Buffer`
+
+```typescript
+import { uploadFile } from '@autonomys/auto-drive'
+
+const api = createAutoDriveApi({ apiKey: 'your-api-key' }) // Initialize your API instance with API key
+const buffer = Buffer.from(...);
+const genericFile = {
+  read: async function *() {
+    yield buffer
+  },
+  name: "autonomys-whitepaper.pdf",
+  mimeType: "application/pdf",
+  size: 1234556,
+  path: "autonomys-whitepaper.pdf"
+}
+
+const options = {
+  password: 'your-encryption-password', // Optional: specify a password for encryption
+  compression: true,
+}
+
+const uploadObservable = uploadFile(api, genericFile, options)
+  .then(() => {
+    console.log('File uploaded successfully!')
   })
   .catch((error) => {
-    console.error('Error retrieving root directories:', error)
+    console.error('Error uploading file:', error)
   })
 ```
+
+### How to upload a folder from folder? (Not available in browser)
+
+```ts
+import { uploadFolderFromFolderPath } from '@autonomys/auto-drive'
+
+const api = createAutoDriveApi({ apiKey: 'your-api-key' }) // Initialize your API instance with API key
+const folderPath = 'path/to/your/folder' // Specify the path to your folder
+
+const options = {
+  uploadChunkSize: 1024 * 1024, // Optional: specify the chunk size for uploads
+  password: 'your-encryption-password', // Optional: If folder is encrypted
+}
+
+const uploadObservable = uploadFolderFromFolderPath(api, folderPath, options)
+```
+
+**Note: If a folder is tried to be encrypted a zip file would be generated and that file would be encrypted and uploaded.**
+
+### Handle observables
+
+Since uploads may take some time, specially in big-sized files. Uploads do implement `rxjs` observables so you could have feedback about the process or even show your users the progress of the upload.
+
+For that reason when file upload functions return `PromisedObservable<UploadFileStatus>`:
+
+```typescript
+export type UploadFileStatus = {
+  type: 'file'
+  progress: number
+  cid?: CID
+}
+```
+
+Being the cid only returned (and thus optional) when the upload is completed.
+
+Similarly, for folder uploads the functions return `PromisedObservable<UploadFolderStatus>`
+
+```ts
+export type UploadFolderStatus = {
+  type: 'folder'
+  progress: number
+  cid?: CID
+}
+```
+
+**e.g Show upload progress in React**
+
+```typescript
+const [progress, setProgress] = useState<number>(0)
+
+useEffect(async () => {
+  const finalStatus = await uploadFileFromInput(api, genericFile, options).forEach((status) => {
+    setProgress(status.progress)
+  })
+})
+```
+
+**e.g Ignore observables**
+
+Other users may want to not use the progress observability. For having a promise instead the field `promise` is a Promise that resolves into `UploadFileStatus` and `UploadFolderStatus` for files and folders respectively.
+
+e.g
+
+```ts
+const status = await uploadFileFromInput(api, genericFile, options).promise
+const cid = status.cid
+```
+
+### Example Usage of Download
+
+Here is an example of how to use the `downloadFile` method to download a file from the server:
+
+```typescript
+import { downloadObject } from '@autonomys/auto-drive'
+
+const api = createAutoDriveApi({ apiKey: 'your-api-key' }) // Initialize your API instance with API key
+
+try {
+    const cid = ".."
+    const stream = await downloadObject(api, { cid })
+    let file = Buffer.alloc(0);
+    for await (const chunk of stream) {
+      file = Buffer.concat([file, chunk])
+    }
+    console.log('File downloaded successfully:', stream)
+} catch (error) {
+    console.error('Error downloading file:', error)
+}
+
+```
+
+### Example Usage of getRoots
+
+Here is an example of how to use the `getRoots` method to retrieve the root directories:
+
+```typescript
+import { createAutoDriveApi, downloadObject } from '@autonomys/auto-drive'
+import fs from 'fs'
+
+const api = createAutoDriveApi({ apiKey: 'your-api-key' }) // Initialize your API instance with API key
+
+try {
+  const stream = fs.createWriteStream('/path/to/file')
+  const asyncBuffer = await downloadObject(api, { cid })
+  for await (const buffer of asyncBuffer) {
+    stream.write(buffer)
+  }
+} catch (error) {
+  console.error('Error downloading file:', error)
+}
+```
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+## Additional Resources
+
+- **Autonomys Academy**: Learn more at [Autonomys Academy](https://academy.autonomys.xyz).
+
+## Contact
+
+If you have any questions or need support, feel free to reach out:
+
+- **GitHub Issues**: [GitHub Issues Page](https://github.com/autonomys/auto-sdk/issues)
+
+We appreciate your feedback and contributions!

package/package.json

@@ -3,7 +3,7 @@
   "packageManager": "yarn@4.2.2",
   "type": "module",
   "main": "dist/index.js",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "author": {
     "name": "Autonomys",
     "url": "https://autonomys.net"
@@ -19,10 +19,10 @@
     "typescript": "^5.6.3"
   },
   "dependencies": {
-    "@autonomys/auto-dag-data": "^1.0.6",
+    "@autonomys/auto-dag-data": "^1.0.8",
     "jszip": "^3.10.1",
     "mime-types": "^2.1.35",
     "zod": "^3.23.8"
   },
-  "gitHead": "2ee93dd0867c16e0a42f2f47b2fa66bc41ba29cf"
+  "gitHead": "88b1b90467db7dd1e301387451ed727189f9808c"
 }