Auto-Drive Package

Introduction

The @autonomys/auto-drive package provides a set of tools to interact with the Autonomys Auto-Drive API.

Features

Autonomys DSN: Permanently store files on the Autonomys’ DSN (Decentralized Store Network).
CID Management: Just like with IPFS, each upload gets its own CID (Content Identifier).
TypeScript Support: Fully typed for an enhanced developer experience.

Auto Drive API documentation

Auto Drive API documentation with all it’s function signatures is available here.

Auto-Drive-API-1

Auto Gateway

Auto gateway is a unified gateway solution designed to seamlessly connect and access files or folders permanently stored on Autonomys Mainnet & Tesnet through a single, streamlined interface. The gateway is available here.

Auto-Gateway-1

How to use Auto Drive SDK?

To interact with the Auto-Drive SDK, you’ll need to create an API key. Follow these steps:

Go to Auto-Drive and login with your preffered SSO.
Once you’re logged in, click on the developers section in the left sidebar menu.
In the developers section, click on ‘Create API Key’
Read the modal message and click on generate

Auto Drive Dashboard

View your upload and download limits, access files uploaded by other users, and manage and share your submissions by logging in to Auto Drive:

Open Auto Drive
Sign in via Google, Discord or GitHub
On the Dashboard you will see:
- Your upload limit (currently 100MB per month)
- Your download limit (currently 5GB per month)
- A list of uploaded files and their CIDs
- Options to Download, Share or Remove each file

Auto-Drive-2

Note: Removing a file does not delete it from the DSN as it is permanent storage. It only removes the file from your Dashboard.

Use the in-browser environment to upload, download or share files, or the SDK functions (described below) to upload files or folders via the CLI.

Auto-Drive-3

Creating an API key

Click on Profile to create your API key. Use this API key in the CLI to upload files or folders.

Auto-Drive-4

Click the Share button next to a file to share it using a link, or provide a user’s public ID to share all their files. Each user’s public ID is visible on their Profile page.

Auto-Drive-5

Installation

Install the package via npm or yarn:

# Using npm
npm install @autonomys/auto-drive
npm install @autonomys/auto-utils
 
# Using yarn
yarn add @autonomys/auto-drive
yarn add @autonomys/auto-utils

Importing

Import the auto-drive functions you need into your project:

// Import specific functions
import { fs,createAutoDriveApi } from '@autonomys/auto-drive';
import { NetworkId } from '@autonomys/auto-utils'
 
// Or import everything
import * as drive from '@autonomys/auto-drive';
import { NetworkId } from '@autonomys/auto-utils'

Available functions

Upload operations

uploadFile(api, file, options): Promise<string>: Uploads a file (using a buffer, File, or a custom interface) with optional encryption and compression. Returns the resulting CID as a string.
uploadFileFromFilepath(api, filePath, options): Promise<string>: Uploads a file from filepath with optional encryption and compression. Returns the resulting CID as a string.
uploadFileFromInput(api, file, options): Promise<string>: Uploads a file obtained from a browser’s File API.
uploadFolderFromInput(api, fileList, options): Promise<string>: Uploads a folder from a browser’s FileList.
uploadFileWithinFolderUpload(api, uploadId, file, options): Promise<string>: Uploads a file within an existing folder upload session.
uploadObjectAsJSON(api, object, name?, options): Promise<string>: Serializes and uploads any object as a JSON file.

Download operations

downloadFile(api, cid, password?): AsyncIterable<Buffer>: Downloads a file from its CID, with optional decryption using a password.
getMyFiles(api, page, limit): Promise<PaginatedResult<ObjectSummary>>: Retrieves paginated list of user’s files.
searchByNameOrCIDInMyFiles(api, value): Promise<ObjectSummary[]>: Searches for files by name or CID within user’s files.
searchByNameOrCID(api, value): Promise<ObjectSummary[]>: Global search for files by name or CID.

Utility functions

getPendingCredits(api): Promise<{ upload: number; download: number }>: Gets the current user’s pending upload and download credits.
getSubscriptionInfo(api): Promise<SubscriptionInfo>: Retrieves the current user’s subscription information.

Network configuration

As Auto Drive is available on both Mainnet and the Taurus testnet, you need to configure the network when using the package:

import { NetworkId } from '@autonomys/auto-utils'
 
const api = createAutoDriveApi({
  apiKey: 'your-api-key',
  network: NetworkId.TAURUS | NetworkId.MAINNET
})

Usage examples

1. Uploading a file from a filepath (Not available in browser)

import { fs,createAutoDriveApi } from '@autonomys/auto-drive'
import { NetworkId } from '@autonomys/auto-utils'
 
const api = createAutoDriveApi({ apiKey: 'your-api-key', network: NetworkId.TAURUS }) // 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,
  // an optional callback useful for large file uploads
  onProgress?: (progress: number) => {
    console.log(`The upload is completed is ${progress}% completed`)
  }
}
 
const cid = await fs.uploadFileFromFilepath(api, filePath, options)
 
console.log(`The file is uploaded and its cid is ${cid}`)

2. Uploading a file using FILE interface

import { uploadFileFromInput, createAutoDriveApi } from '@autonomys/auto-drive'
import { NetworkId } from '@autonomys/auto-utils'
 
const api = createAutoDriveApi({ apiKey: 'your-api-key', network: NetworkId.TAURUS }) // Initialize your API instance with API key
 
// e.g Get File from object from HTML event
const file: File = e.target.value // Substitute with your file
const options = {
  password: 'your-encryption-password', // Optional: specify a password for encryption
  compression: true,
}
const cid = await api.uploadFileFromInput(file, options)
 
console.log(`The file is uploaded and its cid is ${cid}`)

3. Uploading a folder (Not available in browser)

import { createAutoDriveApi, fs } from '@autonomys/auto-drive'
import { NetworkId } from '@autonomys/auto-utils'
 
const api = createAutoDriveApi({ apiKey: 'your-api-key', network: NetworkId.TAURUS }) // 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
  // an optional callback useful for large file uploads
  onProgress: (progress: number) => {
    console.log(`The upload is completed is ${progress}% completed`)
  },
}
 
const folderCID = await fs.uploadFolderFromFolderPath(api, folderPath, options)
 
console.log(`The folder is uploaded and its cid is ${folderCID}`)

4. Uploading a file from a custom interface with `GenericFile`:

import { createAutoDriveApi } from '@autonomys/auto-drive'
import { NetworkId } from '@autonomys/auto-utils'
 
const api = createAutoDriveApi({ apiKey: 'your-api-key', network: NetworkId.TAURUS }) // 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,
  // an optional callback useful for large file uploads
  onProgress?: (progress: number) => {
    console.log(`The upload is completed is ${progress}% completed`)
  }
}
 
const cid = api.uploadFile(genericFile, options)
 
console.log(`The file is uploaded and its cid is ${cid}`)

5. Downloading files

import { createAutoDriveApi } from '@autonomys/auto-drive'
import { NetworkId } from '@autonomys/auto-utils'
 
const api = createAutoDriveApi({ apiKey: 'your-api-key', network: NetworkId.TAURUS }) // Initialize your API instance with API key
 
try {
  const cid = '..'
  const stream = await api.downloadFile(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)
}

6. Creating shareable download link

import { createAutoDriveApi } from '@autonomys/auto-drive'
import { NetworkId } from '@autonomys/auto-utils'
 
const api = createAutoDriveApi({ apiKey: 'your-api-key', network: NetworkId.TAURUS }) // Initialize your API instance with API key
 
try {
  const cid = 'your-file-cid'
  const publicUrl = await api.publishObject(cid)
  console.log('Public download URL:', publicUrl)
} catch (error) {
  console.error('Error publishing object:', error)
}

7. Example usage of `getMyFiles`

Here is an example of how to use the getMyFiles method to retrieve the root directories:

import { createAutoDriveApi } from '@autonomys/auto-drive'
import { NetworkId } from '@autonomys/auto-utils'
 
const api = createAutoDriveApi({ apiKey: 'your-api-key', network: NetworkId.TAURUS }) // Initialize your API instance with API key
 
try {
  for (let i = 0; i < 10; i++) {
    const myFiles = await api.getMyFiles(i, 100)
    console.log(`Retrieved ${myFiles.rows.length} files of ${myFiles.totalCount} total`)
    for (const file of myFiles.rows) {
      console.log(`${file.name} - ${file.headCid}: ${file.size}`)
    }
  }
} catch (error) {
  console.error('Error downloading file:', error)
}

Auto Consensus Auto Utils