Merge pull request #145 from autonomys/feat/auto-drive-api

Add auto-drive package for managing API interaction

packages/auto-drive/README.md

@@ -0,0 +1,74 @@
+# auto-drive
+
+## auto-drive API Tools
+
+The `auto-drive` package provides a set of tools to interact with the auto-drive API. Below are some key functionalities:
+
+### Installation
+
+To install the package, use the following command:
+
+```bash
+yarn add @autonomys/auto-drive
+```
+
+### How to use it?
+
+### Example Usage
+
+Here is an example of how to use the `uploadFile` method to upload a file with optional encryption and compression:
+
+```typescript
+import { uploadFile } from '@autonomys/auto-drive'
+
+const api = new AutoDriveApi() // Initialize your API instance
+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)
+  .then(() => {
+    console.log('File uploaded successfully!')
+  })
+  .catch((error) => {
+    console.error('Error uploading file:', error)
+  })
+```
+
+### Example Usage of Download
+
+Here is an example of how to use the `downloadFile` method to download a file from the server:
+
+```typescript
+import { getRoots } from '@autonomys/auto-drive'
+
+const api = new AutoDriveApi() // Initialize your API instance
+
+getRoots(api)
+  .then((roots) => {
+    console.log('Root directories:', roots)
+  })
+  .catch((error) => {
+    console.error('Error retrieving root directories:', error)
+  })
+```
+
+### Example Usage of getRoots
+
+Here is an example of how to use the `getRoots` method to retrieve the root directories:
+
+```typescript
+import { getRoots } from '@autonomys/auto-drive'
+
+const api = new AutoDriveApi() // Initialize your API instance
+
+getRoots(api)
+  .then((roots) => {
+    console.log('Root directories:', roots)
+  })
+  .catch((error) => {
+    console.error('Error retrieving root directories:', error)
+  })
+```

packages/auto-drive/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@autonomys/auto-drive",
+  "packageManager": "yarn@4.2.2",
+  "type": "module",
+  "main": "dist/index.js",
+  "author": {
+    "name": "Autonomys",
+    "url": "https://autonomys.net"
+  },
+  "scripts": {
+    "build": "tsc"
+  },
+  "devDependencies": {
+    "@types/mime-types": "^2",
+    "typescript": "^5.6.3"
+  },
+  "dependencies": {
+    "@autonomys/auto-dag-data": "workspace:^",
+    "mime-types": "^2.1.35",
+    "zod": "^3.23.8"
+  }
+}

packages/auto-drive/src/api/calls/download.ts

@@ -0,0 +1,21 @@
+import { ArgsWithoutPagination } from '../../utils/types.ts'
+import { AutoDriveApi } from '../connection.ts'
+
+export const downloadObject = async (
+  api: AutoDriveApi,
+  query: ArgsWithoutPagination<{ cid: string }>,
+): Promise<ReadableStream<Uint8Array>> => {
+  const response = await api.sendRequest(`/objects/${query.cid}/download`, {
+    method: 'GET',
+  })
+
+  if (!response.ok) {
+    throw new Error(`Failed to download file: ${response.statusText}`)
+  }
+
+  if (!response.body) {
+    throw new Error('No body returned from download request')
+  }
+
+  return response.body
+}

packages/auto-drive/src/api/calls/index.ts

@@ -0,0 +1,4 @@
+export * from './download.ts'
+export * from './read.ts'
+export * from './upload.ts'
+export * from './write.ts'

packages/auto-drive/src/api/calls/read.ts

@@ -0,0 +1,194 @@
+import { ArgsWithoutPagination, ArgsWithPagination } from '../../utils/types.ts'
+import { AutoDriveApi } from '../connection.ts'
+import { ObjectInformation, ObjectSummary, Scope } from '../models/objects.ts'
+
+/**
+ * Retrieves the root objects based on the specified scope.
+ *
+ * @param {AutoDriveApi} api - The API instance used to send requests.
+ * @param {ArgsWithPagination<{ scope: Scope }>} query - The query parameters including scope, limit, and offset.
+ * @returns {Promise<ObjectSummary[]>} - A promise that resolves to an array of ObjectSummary representing the root objects.
+ * @throws {Error} - Throws an error if the request fails.
+ */
+export const getRoots = async (
+  api: AutoDriveApi,
+  query: ArgsWithPagination<{ scope: Scope }>,
+): Promise<ObjectSummary[]> => {
+  const response = await api.sendRequest(
+    `/objects/roots?scope=${query.scope}&limit=${query.limit}&offset=${query.offset}`,
+    {
+      method: 'GET',
+    },
+  )
+
+  if (!response.ok) {
+    throw new Error(`Failed to get roots: ${response.statusText}`)
+  }
+
+  return response.json()
+}
+
+/**
+ * Retrieves the objects that have been shared with the authenticated user.
+ *
+ * This method sends a request to the server to fetch a list of objects
+ * that are shared with the user, based on the specified pagination parameters.
+ *
+ * @param {AutoDriveApi} api - The API instance used to send requests.
+ * @param {ArgsWithPagination} query - The query parameters including limit and offset for pagination.
+ * @returns {Promise<ObjectSummary[]>} - A promise that resolves to an array of ObjectSummary representing the shared objects.
+ * @throws {Error} - Throws an error if the request fails.
+ */
+export const getSharedWithMe = async (
+  api: AutoDriveApi,
+  query: ArgsWithPagination,
+): Promise<ObjectSummary[]> => {
+  const response = await api.sendRequest(
+    `/objects/roots/shared?limit=${query.limit}&offset=${query.offset}`,
+    {
+      method: 'GET',
+    },
+  )
+
+  if (!response.ok) {
+    throw new Error(`Failed to get shared with me: ${response.statusText}`)
+  }
+
+  return response.json()
+}
+
+/**
+ * Retrieves the objects that have been marked as deleted.
+ *
+ * This method sends a request to the server to fetch a list of objects
+ * that have been deleted, based on the specified pagination parameters.
+ *
+ * @param {AutoDriveApi} api - The API instance used to send requests.
+ * @param {ArgsWithPagination} query - The query parameters including limit and offset for pagination.
+ * @returns {Promise<ObjectSummary[]>} - A promise that resolves to an array of ObjectSummary representing the deleted objects.
+ * @throws {Error} - Throws an error if the request fails.
+ */
+export const getDeleted = async (
+  api: AutoDriveApi,
+  query: ArgsWithPagination,
+): Promise<ObjectSummary[]> => {
+  const response = await api.sendRequest(
+    `/objects/roots/deleted?limit=${query.limit}&offset=${query.offset}`,
+    {
+      method: 'GET',
+    },
+  )
+
+  if (!response.ok) {
+    throw new Error(`Failed to get deleted: ${response.statusText}`)
+  }
+
+  return response.json()
+}
+
+/**
+ * Retrieves the aggregated information of a specific object identified by its CID.
+ *
+ * This method sends a request to the server to fetch details about the
+ * object, including its metadata and other relevant information.
+ *
+ * @param {AutoDriveApi} api - The API instance used to send requests.
+ * @param {ArgsWithoutPagination<{ cid: string }>} query - The query parameters containing the CID of the object to retrieve.
+ * @returns {Promise<ObjectInformation>} - A promise that resolves to the information of the requested object.
+ * @throws {Error} - Throws an error if the request fails.
+ */
+export const getObject = async (
+  api: AutoDriveApi,
+  query: ArgsWithoutPagination<{ cid: string }>,
+): Promise<ObjectInformation> => {
+  const response = await api.sendRequest(`/objects/${query.cid}`, {
+    method: 'GET',
+  })
+
+  if (!response.ok) {
+    throw new Error(`Failed to get object: ${response.statusText}`)
+  }
+
+  return response.json()
+}
+
+/**
+ * Retrieves the upload status of a specific object identified by its CID.
+ *
+ * This method sends a request to the server to fetch the current upload status
+ * of the object, which can indicate whether the upload is pending, completed,
+ * or failed.
+ *
+ * @param {AutoDriveApi} api - The API instance used to send requests.
+ * @param {ArgsWithoutPagination<{ cid: string }>} query - The query parameters containing the CID of the object whose upload status is to be retrieved.
+ * @returns {Promise<ObjectInformation['uploadStatus']>} - A promise that resolves to the upload status of the requested object.
+ * @throws {Error} - Throws an error if the request fails.
+ */
+export const getObjectUploadStatus = async (
+  api: AutoDriveApi,
+  query: ArgsWithoutPagination<{ cid: string }>,
+): Promise<ObjectInformation['uploadStatus']> => {
+  const response = await api.sendRequest(`/objects/${query.cid}/status`, {
+    method: 'GET',
+  })
+
+  if (!response.ok) {
+    throw new Error(`Failed to get object: ${response.statusText}`)
+  }
+
+  return response.json()
+}
+
+/**
+ * Retrieves the owners of a specific object identified by its CID.
+ *
+ * This method sends a request to the server to fetch the list of owners
+ * associated with the object. The owners can provide insights into who
+ * has access to or control over the object.
+ *
+ * @param {AutoDriveApi} api - The API instance used to send requests.
+ * @param {ArgsWithoutPagination<{ cid: string }>} query - The query parameters containing the CID of the object whose owners are to be retrieved.
+ * @returns {Promise<ObjectInformation['owners']>} - A promise that resolves to the list of owners of the requested object.
+ * @throws {Error} - Throws an error if the request fails.
+ */
+export const getObjectOwners = async (
+  api: AutoDriveApi,
+  query: ArgsWithoutPagination<{ cid: string }>,
+): Promise<ObjectInformation['owners']> => {
+  const response = await api.sendRequest(`/objects/${query.cid}/owners`, {
+    method: 'GET',
+  })
+
+  if (!response.ok) {
+    throw new Error(`Failed to get object: ${response.statusText}`)
+  }
+
+  return response.json()
+}
+
+/**
+ * Retrieves the metadata of a specific object identified by its CID.
+ *
+ * This method sends a request to the server to fetch the metadata associated
+ * with the object. The metadata can include various details about the object,
+ * such as its name, type, size, and other relevant information.
+ *
+ * @param {AutoDriveApi} api - The API instance used to send requests.
+ * @param {ArgsWithoutPagination<{ cid: string }>} query - The query parameters containing the CID of the object whose metadata is to be retrieved.
+ * @returns {Promise<ObjectInformation['metadata']>} - A promise that resolves to the metadata of the requested object.
+ * @throws {Error} - Throws an error if the request fails.
+ */
+export const getObjectMetadata = async (
+  api: AutoDriveApi,
+  query: ArgsWithoutPagination<{ cid: string }>,
+): Promise<ObjectInformation['metadata']> => {
+  const response = await api.sendRequest(`/objects/${query.cid}/metadata`, {
+    method: 'GET',
+  })
+
+  if (!response.ok) {
+    throw new Error(`Failed to get object: ${response.statusText}`)
+  }
+
+  return response.json()
+}